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Abstract 


This  report  is  one  in  a  series  that  documents  the  Weather  and 
Atmospheric  Visualization  Effects  for  Simulation  (WAVES)  suite  of 
models.  Each  volume  describes  an  aspect  of  the  models.  This 
particular  report  describes  the  status  of  the  software  development 
that  supports  the  WAVES  suite  of  models.  WAVES  is  a  suite  of 
atmospheric  radiation  models  designed  to  calculate  illumination  and 
propagation  effects  for  a  given  area.  The  U.S.  Army  Research 
Laboratory  (ARE)  has  developed  the  models  over  the  past  decade. 
The  individual  components  of  WAVES  have  reached  such  a  level  of 
scientific  maturity  that  a  formal  software  delivery  plan  is  being 
undertaken.  This  work  is  particularly  important  given  the  Army's 
interest  in  integrating  WAVES  into  large-scale  Department  of 
Defense  simulators. 
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1.  Introduction 


This  report  is  one  in  a  series  of  U.S.  Army  Research  Laboratory  (ARL) 
reports  (ARL-TR-1721-1  to  8)  that  documents  the  WAVES  (Weather  and 
Atmospheric  Visualization  Effects  for  Simulation)  suite  of  models  d  A 
number  of  experimental  and  computational  validations  have  been  con¬ 
ducted  for  WAVES.  These  previous  studies  contribute  to  the  model 
evaluation  of  WAVES. 

TASC/Litton,  Inc.,  was  awarded  a  contract  in  late  1997  to  implement  a 
software  design  that  would  satisfy  the  Army's  requirements.  A  software 
requirements  review  was  held  on  October  20, 1997,  where  a  software 
design  was  proposed  to  the  government.  The  approved  design  addresses 
the  complex  problem  of  integrating  vastly  different  types  of  software  over 
a  short  period  of  time  with  limited  human  resources.  Nearly  all  the 
existing  numerical  modeling  code  is  written  in  flavors  of  Eortran  66  and 
Eortran  77;  none  is  object-oriented.  The  large-scale  simulators,  on  the 
other  hand,  require  strict  adherence  to  object-oriented  design  (OOD) 
under  the  guise  of  High  Level  Architecture  (HLA),  a  Department  of 
Defense  (DoD)  software  standard.  Participation  in  any  of  the  simulations 
requires  that  the  candidate  code  have  an  application-programmer  inter¬ 
face  (API)  that  is  HLA-compliant.  After  it  was  determined  that  there  were 
not  enough  resources  to  build  an  API  for  WAVES  that  would  meet  this 
prerequisite,  it  was  decided  that  WAVES  should  be  structured  as  a 
"toolkit"  that  had  an  interface  using  updated  software  design  patterns. 
Such  a  toolkit  would  be  able  to  interact  seamlessly  with  a  variety  of 
applications,  ranging  from  simple  user  programs  to  large  environmental 
models.  The  design  leaves  the  legacy  code,  buried  beneath  the  interface, 
virtually  unchanged. 

In  December  1997,  the  developers  of  the  environmental  server  TAOS 
(Total  Atmosphere-Ocean  System)  agreed  to  implement  WAVES  as  a 
client  application  using  the  proposed  interface.  TAOS  is  already  used  in  a 
number  of  DoD  simulations  and  is  fully  HLA-compliant.  Such  integration 
will  allow  simulators  to  access  WAVES  via  TAOS,  and  will  avoid  the  need 
to  build  an  expensive,  HLA-compliant  API  for  WAVES. 


’^The  appendix  of  this  report  describes  the  volumes  in  this  series. 
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2.  The  WAVES  Toolkit 


The  resulting  WAVES  Toolkit  design  consists  of  each  numerical  model 
component  wrapped  in  an  interface  written  in  the  C++  programming 
language.  Data  objects,  which  contain  the  output  of  the  numerical  models, 
are  a  collection  of  data  and  functions  used  for  manipulating  the  output. 
The  collection  of  the  numerical  model  objects  and  the  data  objects  is 
defined  as  a  scenario:  i.e.,  a  complete  instance  of  a  WAVES  simulation. 
Scenarios  provide  methods  to  set  up  and  execute  the  various  models  as 
well  as  manage  all  relevant  model  output.  It  is  highly  desirable  that  the 
WAVES  scenarios  be  easily  created  and  controlled  by  user  programs  or  by 
simulators.  The  scenarios  should  also  be  able  to  attach  easily  to  a  graphi¬ 
cal  user  interface  (GUI).  The  design  proposed  for  the  toolkit  ensures  that 
all  these  criteria  may  be  satisfied. 

WAVES  consists  of  five  major  numerical  models:  MODTRAN  (moderate 
resolution  transmission  model),  the  Solar  Lunar  Almanac  (SLAG),  the 
Cloud  Scene  Simulation  Model  (CSSM),  ATMOS,  and  the  Boundary  Layer 
Illumination  and  Radiative  Balance  Model  (BLIRB).  The  MODTRAN 
model  defines  the  boundary  conditions  for  the  simulation  area. 
MODTRAN  provides  the  solar  irradiance  at  the  top  of  the  region,  along 
with  the  path-scattered  radiance  and  molecular  transmission  inside  the 
region.  SLAG  is  a  model  that  calculates  sun  and  moon  positions  for  a 
given  date,  time,  and  location.  CSSM  is  a  statistical  model  that  generates 
realistic  clouds  using  fractal  techniques  [1].  The  clouds  generated  by 
CSSM  impact  the  direct  solar  radiation,  the  diffuse  radiation,  and  the 
amount  of  light  reflected  in  the  region.  ATMOS  is  an  optical  turbulence 
model,  used  primarily  at  visible  and  infrared  wavelengths.  BLIRB  is  a 
discrete-ordinates  multistream  radiative  transfer  model.  It  computes 
direct  and  diffuse  radiation  from  the  surface  of  the  earth  up  to  12  km  [2]. 

2.1  Object-Oriented  Design  Concepts 

The  WAVES  Toolkit  is  being  constructed  using  established  OOD  concepts. 
Like  its  predecessor,  modular  design,  which  was  developed  and  empha¬ 
sized  in  the  1970s,  OOD  supports  the  idea  of  modeling  real-world  build¬ 
ing  blocks  in  the  development  of  source  code.  Modular  design,  however, 
stresses  the  concept  of  top-down  decomposition:  a  main  routine  exists, 
which  relies  on  calling  other  routines  for  full  implementation.  OOD 
diverges  from  this  concept  by  reasoning  that  real-world  systems  do  not 
function  in  a  top-down  manner.  Under  OOD,  the  routines  are  objects  with 
specific  functionality  and  data  members,  but  they  have  no  direct  relation¬ 
ship  to  a  main  routine.  Such  a  relationship  may  impede  future  changes  to 
the  code,  and  the  software  is  more  likely  to  be  rebuilt  in  the  future. 

The  software  design  for  the  WAVES  Toolkit  is  derived  from  the  teachings 
of  Goad  [3],  Main  and  Savitch  [4],  and  Free  [5].  The  style  endorsed  by 
these  software  engineers  has  been  successfully  implemented  on  a  number 
of  projects  at  the  Johannes  Kepler  University  in  Linz,  Austria.  This  style 
emphasizes  the  use  of  abstract  data  types  and  structures,  the  principles  of 
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hiding  implementation  detail  and  data  within  the  confines  of  an  object, 
and  the  concept  of  dynamic  binding.  A  complete  discussion  of  object- 
oriented  software  design  is  well  beyond  the  scope  of  this  document; 
however,  a  brief  description  of  how  these  three  practices  are  formulated  is 
necessary  before  discussing  the  details  of  the  WAVES  Toolkit  software 
design. 

Abstraction  of  fundamental  software  components  helps  to  reduce  of  the 
complexity  of  a  particular  application.  A  significant  number  of  details 
must  be  considered  in  designing  software,  such  as  structuring  the  design 
aids  in  simplifying  the  problem  under  consideration.  Appropriate  struc¬ 
turing  is  accomplished  by  dividing  the  problem  up  into  modules  that  can 
be  considered  independent  tasks.  This  attribute  allows  the  software  to  be 
better  understood  and  subsequently  easier  to  extend  and  reuse.  There  are 
numerous  advantages  to  developing  software  that  may  be  easily  reused. 
Software  reuse  reduces  the  overall  cost  of  a  project  by  ensuring  that  the 
wheel  will  not  be  reinvented.  Existing  software,  which  has  already  been 
validated,  is  less  likely  to  contain  errors  than  newly  written  code.  Reus¬ 
able  software  also  is  more  likely  to  be  portable  across  multiple  platforms. 
The  WAVES  Toolkit  defines  two  major  abstract  data  structures — the 
scenario  objects  and  data  objects — which  are  discussed  in  more  detail 
later. 

One  of  the  most  important  elements  of  OOD  is  information  hiding.  Objects 
must  be  defined  so  that  design  decisions,  implementation  details,  and 
instance  variables  are  hidden  from  view.  By  software  designed  this  way, 
the  chances  of  building  reusable  components  increase.  The  C-i-i-  language, 
used  by  the  WAVES  Toolkit,  provides  information  hiding  in  the  form  of 
private  variables  and  data  structures. 

The  concept  of  dynamic  binding  implies  that  messages  to  objects  are 
determined  during  execution,  not  at  the  time  of  compilation.  Dynamic 
binding,  as  discussed  by  Free  [5],  is  a  precondition  for  development  of 
reusable  software  architectures  that  do  not  depend  on  specific  object 
types.  Within  the  WAVES  Toolkit,  all  the  major  components  are  instanti¬ 
ated  dynamically,  and  destructors  are  used  with  all  objects  to  minimize 
the  risk  of  memory  bleeding. 

2.2  Overview  of  the  Toolkit  Design 

The  design  and  present  development  status  of  the  WAVES  Toolkit  is 
depicted  in  figures  1  and  2.  Abstraction  of  a  complete  WAVES  scenario  is 
represented  by  the  box  displayed  in  the  upper  left  corner  of  figure  1:  this 
is  the  Scenario  class.  This  class  contains  all  the  data  structures  neces¬ 
sary  to  construct  and  invoke  a  WAVES  experiment.  The  Scenario  class 
essentially  is  a  collection  of  private  data  members  and  other  class  objects. 
The  construction  of  a  class  that  consists  of  other  classes  is  known  as 
containment.  The  concept  of  containment  extends  beyond  the  Scenario 
class;  it  is  used  in  the  contained  objects  as  well. 
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Figure  1.  Overview  and  current  status  of  the  SCENARIO  object.  Status  report  valid  as  of  March  22, 
1999. 
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Figure  2.  Overview  of  the  functional  WAVES  system.  Model  object  notation  [6]  is  used.  Color  coding 
as  in  figure  1. 
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The  objects  contained  within  Scenario  fall  into  two  categories:  model 
objects  and  ancillary  objects.  The  model  objects  consist  of  the  main  scien¬ 
tific  "core"  elements  of  WAVES:  MODTRAN,  SLAC,  CSSM,  ATMOS,  and 
BLIRB.  Additional  models,  such  as  the  three-dimensional  smoke  model 
COMBIC  (combined  obscurants  model  and  battlefield-induced  contami¬ 
nants),  may  be  contained  within  Scenario  in  the  future  without  disrup¬ 
tion  of  other  model  objects.  The  ancillary  objects  consist  of  a  collection  of 
data  objects,  which  are  discussed  in  the  next  section,  and  the  error  object. 
The  latter  is  a  persistent  object  that  allows  the  user  to  trace  system  opera¬ 
tions.  Many  types  of  notes  and  errors,  both  fatal  and  nonfatal,  may  be 
logged  easily  via  the  error  object.  At  the  end  of  a  WAVES  scenario  execu¬ 
tion,  or  at  any  time  during  execution,  the  error  log  may  be  dumped  and 
the  messages  retrieved.  The  toolkit  does  not  normally  route  error  mes¬ 
sages  directly  to  the  screen. 

As  mentioned  previously,  the  Scenario  class  is  abstract,  not  concrete.  It 
defines  an  organizational  concept  for  containment  of  the  model  objects 
and  the  ancillary  objects.  It  provides  a  useful  framework  for  future  expan¬ 
sion  of  the  system.  However,  it  does  very  little  work.  The  manipulation  of 
a  WAVES  scenario  involves  implementing  a  series  of  commands  that 
execute  the  various  models  and  move  data  back  and  forth  as  required. 
These  commands  may  change  between  users  or  between  simulators  that 
invoke  WAVES.  In  previous  versions  of  WAVES,  this  type  of  program  was 
known  simply  as  a  driver.  Within  the  toolkit,  this  functionality  is  known 
as  an  event  handler.  Event  handlers  may  be  tailored  for  specific  applica¬ 
tions;  therefore,  it  is  possible  that  each  application  may  have  a  unique 
event  handler.  The  Scenario  class,  on  the  other  hand,  is  not  designed  to 
be  altered.  The  event  handlers  used  within  the  toolkit  derive  all  the 
properties  of  the  Scenario  class,  hence  they  are  objects  that  possess  the 
property  of  inheritance.  A  full  perspective  of  the  toolkit  is  depicted  in 
figure  2.  In  this  figure,  the  object  model  notation  of  Rumbaugh  et  al  [6]  is 
used.  The  figure  depicts  the  derivation  of  the  event  handler  from  the 
Scenario  class.  Presently,  there  is  a  single  event  handler  class  available 
for  the  toolkit,  unglamorously  named  Event. 

The  methods  for  the  Event  class  perform  all  the  functions  necessary  to 
execute  WAVES.  Hence,  Event  is  a  functional  API  that  may  be  interfaced 
easily  to  a  user  program,  a  GUI,  or  a  simulator.  Details  of  the  methods 
and  data  members  of  the  Scenario  and  the  Event  classes  are  provided 
later  in  this  report. 

Where  to  Find  the  Software 

This  document  describes  the  software  currently  under  development  at  the 
ARE  facility  in  Adelphi,  Maryland,  where  WAVES  executes  on  an  eight- 
processor  Silicon  Graphics  Onyx  computer.  The  hostname  for  this  ma¬ 
chine  is  raman .  arl .  mil.  On  this  machine,  the  software  is  organized  as 
follows: 


•  /usr/ waves/ 

-"Top-level"  directories  containing  current  and  previous  versions  of  the 
models 

•  /usr /waves /Classes/ 

-  Header  files  and  implementation  files  for  the  C-i-i-  wrappers 

-  User  programs  that  invoke  the  API 

-  Makefile  for  the  toolkit  (links  to  model  object  code,  below) 

-  Object  code  for  the  wrappers 

-  Model  executable 

/  usr  /  waves  /  ModelObj  ectCode  /  BLIRB  / 

•  /  usr  /  waves  /  ModelObj  ectCode  /  CSSM  / 

•  /  usr  /  waves  /  ModelObj  ectCode  /  MODTRAN  / 

•  /  usr  /  waves  /  ModelObj  ectCode  /  SL  AC  / 

-  Object  code  for  the  various  models 

•  /  usr  /  waves  /  ModelSourceCode  /  BLIRB  / 

•  /  usr  /  waves  /  ModelSourceCode  /  CSSM  / 

•  /  usr  /  waves  /  ModelSourceCode  /  MODTRAN  / 

•  /  usr  /  waves  /  ModelSourceCode  /  SL  AC  / 

-  Source  code  for  the  various  models 

-  Makefiles  exist  for  each  of  the  models;  object  code  is  placed  in  the 
ModelObj ectCode  directory 

•  /usr /waves /Classes /DATA/ 

-  Various  data  files  required  by  the  models 

•  /usr/ waves /OutFiles/ 

-  Storage  location  for  data  objects  generated  during  model  execution 

•  /usr/ waves /VisSD 

-  Visualizaton  object. 

Within  the  source  code,  references  to  top-level  directories  are  not  made  so 
that  WAVES  may  be  implemented  easily  on  other  platforms.  However, 
subdirectories  that  exist  underneath  are  referenced  explicitly.  The  envi¬ 
ronment  variable  $WAVESDIR  is  used  to  reference  indirectly  the  top  level 
of  the  directory.  In  the  current  implementation,  the  value  of  $WAVESDIR 
is  /usr/waves/. 
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3.  Data  Objects 

Data  objects  provide  methods  for  storing  and  retrieving  model  output. 
They  allow  the  user  to  manage  large  amounts  of  information  without 
requiring  knowledge  of  dataset  formats,  locations  of  files,  position  of 
information  within  datasets,  etc.  They  also  provide  a  means  of  communi¬ 
cating  information  within  an  event  handler.  The  methods  of  the  data 
objects  allow  the  user  to  specify  symbolic  identifiers  for  an  experiment  as 
well  as  grid  information  unique  to  individual  quantities.  Employing  the 
methods  of  the  data  objects  to  save  and  retrieve  information  allows 
dataset  formats  to  be  altered  easily,  should  that  be  necessary.  No  subse¬ 
quent  changes  are  required  to  user  programs  or  to  the  event  handler. 
Currently,  the  WAVES  Toolkit  contains  one  class  named  DataOb  ject  and 
descendent  classes  that  are  tailored  to  a  specific  model.  DataOb  ject  is 
portrayed  in  figure  3  using  object  model  notation. 


DataObject(  int )  ■ 

DataObjectTchar^T^ 

DataObject(sti1ng)H 

DataObject(  const  string&, 
const  string&,  const 
string&,  const  string&, 
const  string&,  int,  int ) 

getQuanQ  H 

save()  H 


DataObject 


queryO 

accessQ 

putGridQ 

getGridQ 

putQuanQ 


getHeaderQ 


Internal  file 
pointer 


MODTRAN 

CSSM  ■ 

BLIRB 

Results 

Results 

Results 

ATMOS 

Results 


Figure  3.  Details  of  DataObject  class.  Descendent  classes  (without  detail)  are  shown  at  the  bottom  of 
the  diagram.  Color  coding  as  in  figure  1. 
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3.1  The  WAVES  Toolkit  Format 

ARL  has  selected  a  relatively  lucid  format  for  storing  information  within 
the  data  objects.  This  is  the  WAVES  Toolkit  Format  (WTF).  Three  data 
types  are  represented  by  this  format  and  contained  within  the  structure 
named  data;  they  are  header,  grid,  and  quantity.  Dynamic  allocation 
is  always  used  within  the  data  objects,  hence  the  structure  appears  as 
follows: 

struct  data  { 

header  *headerlnf o; 

grid  *gridInfo; 

quantity  *quanInfo; 

}; 

Within  this  structure  the  component  data  types  are  defined  as 

struct  header  { 

string  sFileFlags,  sJobTitle,  sExpID,  sExpDate, 
sExecuteDate; 

int  numGrids,  numQuantities; 

float  fGridRefLat,  fGridRefLon,  f GridRefHeight; 

}; 

struct  grid  { 

int  gridindex,  numEastWest,  numNorthSouth,  numVertical, 

numTimes,  numWavelengths; 

float  SWxOrigin,  SWyOrigin,  *levels,  *wavelengths ; 

In¬ 
struct  quantity  { 

string  sqlD,  sLabel; 

int  gridindex; 

float  *fData; 

}; 

The  variables  within  the  header  structure  are  summarized  below.  Only  one 
header  is  defined  per  data  object. 
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•  sFileFlags:  Astring  identifying  special  characteristics  of  the  data 
object.  Reserved  for  future  use. 

•  s  JobTitle:  A  description  of  the  contents  of  the  data  object. 

•  s  Exp  ID:  A  string  representing  the  experiment  number  of  the  scenario. 

•  sExpDate:  A  string  representing  the  date  and  time  of  the  experiment,  in 
the  format  YYYYMMDDHHMM. 

•  sExecuteDate:  A  string  representing  the  date  and  time  the  experiment 
was  executed,  in  the  format  YYYYMMDDHHMM. 

•  numGrids:  The  total  number  of  grids  defined. 

•  numQuantities:  The  total  number  of  variables  or  quantities  defined. 

•  f  GridRef  Lat:  A  reference  latitude.  Reserved  for  future  use. 

•  f  GridRefLon:  Areference  longitude.  Reserved  for  future  use. 

•  fGridRefHeight:A  reference  height.  Reserved  for  future  use. 

The  variables  within  the  grid  structure  are  summarized  below.  There  is  no 
limit  to  the  number  of  grids  the  user  may  define.  For  quantities,  five 
dimensions  (x,  y,  z,  t,  and  X)  are  always  defined.  The  sizes  of  these  dimen¬ 
sions  are  within  the  header's  grid  information. 

•  gridindex:  The  grid  identifier;  the  first  grid  is  numbered  0. 

•  numEastWest:  Number  of  east-west  points  within  grid. 

•  numNorthSouth:  Number  of  north-south  points  within  grid. 

•  numVertical:  Number  of  points  along  the  vertical  axis. 

•  numTime s:  Number  of  points  in  the  temporal  dimension. 

•  numWavelengths:  Number  of  points  in  the  frequency  dimension. 

•  SWxOrigin:  Longitude  of  the  southwest  corner  point. 

•  SWyOrigin:  Latitude  of  the  southwest  corner  point. 

•  levels:  Address  of  the  first  element  of  an  array  containing  the  height,  in 
kilometers,  of  each  vertical  level  of  the  grid. 

•  wavelengths:  Address  of  the  first  element  of  an  array  containing  the 
wavenumbers,  in  cm“^,  of  each  wavenumber  represented  in  the  grid. 

The  variables  within  the  quantity  structure  are  summarized  below.  All 
quantities  are  five-dimensional  but  stored  as  a  one-dimensional  array, 
with  the  outermost  dimension  changing  the  fastest.  The  following  logic 
will  perform  such  a  transformation: 

for  v=0 , numWavelengths-1 
for  w=0 , numTime s-1 
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for  x=0 , numEastWest-1 
for  y=0 , numNorthSouth-1 
for  z=0 , numVertical-1 

fiveD_ref  =  v  *  (numTimes  *  numEastWest  *  numNorthSouth  *  numLevels)  + 
w  *  (numEastWest  *  numNorthSouth  *  numLevels)  + 

X  *  (numNorthSouth  *  numLevels)  + 
y  *  (numLevels)  + 

z; 

•  sqlD:  A  mnemonic  used  for  identifying  a  particular  quantity.  This 
mnemonic  is  later  used  to  retrieve  the  quantity  from  an  existing  data 
object. 

•  s  Labe  1 :  A  statement  describing  the  current  quantity. 

•  gridindex:  The  grid  identifier  matched  with  the  current  quantity. 

•  f  Data:  The  address  of  the  starting  element  of  an  array  containing  output 
data  for  the  current  quantity. 

The  methods  for  DataOb  ject  are  depicted  in  figure  3  at  the  location  of 
the  module  interface.  A  summary  of  each  method  follows. 

•  DataOb  ject  (  int  ) :  This  constructor  is  used  to  initialize  an  existing 
data  object.  The  integer  passed  is  the  experiment  identifier.  The  object  is 
opened  READ  ONLY. 

•  DataOb  ject  (  char*  ) :  This  constructor  initializes  an  existing  data 
object.  The  character  constant  is  the  name  of  the  dataset  containing  the 
data  object.  The  object  is  opened  READ  ONLY. 

•  DataOb  ject  (  string  ) :  This  constructor  initializes  an  existing  data 
object.  The  string  variable  is  the  name  of  the  dataset  containing  the  data 
object.  The  object  is  opened  READ  ONLY. 

•  DataObject(  const  strings,  const  strings,  const 
Strings,  const  strings,  const  strings,  int,  int  ) : This 
constructor  initializes  a  new  data  object.  The  arguments  passed  to  the 
constructor  are  the  first  seven  elements  of  the  header  data  structure.  The 
object  is  opened  WRITE  ONLY. 

•  query  (  ) :  Invoking  this  function  will  route  a  README-like  description 
of  the  quantities  inhabiting  the  data  object.  The  description  is  sent  to  the 
error  object  at  error  level  1  (see  description  of  the  error  object)  or  to  the 
screen,  if  this  option  is  available. 

•  acces  s  (  ) :  This  function  performs  all  the  input  and  output  (1/ O) 
necessary  to  retrieve  information  from  an  existing  data  object.  It  must  be 
issued  after  the  constructor  is  invoked  and  before  any  attempt  is  made  to 
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retrieve  grid  or  quantity  information,  otherwise  an  error  is  logged.  Addi¬ 
tional  calls  to  acces  s  (  )  are  ignored.  This  function  is  not  used  when 
creating  a  new  data  object. 

putGrid(  int,  int,  int,  int,  int,  int,  float,  float, 
float*,  float*  ):  Initializes  grids  within  the  data  object.  The  argu¬ 
ments  passed  to  this  function  are  the  variables  and  arrays  contained 
within  structure  grid. 

putQuan  (  const  strings,  const  strings,  int,  float*  ): 

Initializes  quantities  within  the  data  object.  The  arguments  passed  to  this 
function  are  the  variables  and  the  array  contained  within  structure 

quantity. 

getGrid(  int,  intS,  intS,  intS,  intS,  intS,  floats, 
floats,  float*s,  float*s  ):  Retrieves  grids  within  the  data 
object.  The  arguments  returned  from  this  function  are  the  variables  and 
arrays  contained  within  structure  grid. 

getQuan (  const  strings,  const  strings,  int,  float*  ): 

Retrieves  quantities  within  the  data  object.  The  arguments  returned  from 
this  function  are  the  variables  and  the  array  contained  within  structure 

quantity. 

getHeader (  strings,  strings,  strings,  strings, 

Strings,  intS,  intS  ) :  Retrieves  header  information  from  the  data 
object.  The  arguments  that  are  returned  from  this  function  are  the  vari¬ 
ables  and  the  array  contained  within  structure  header. 

save  (  ) :  Writes  all  the  data  object  contents  to  a  disk  file.  The  destructor 
automatically  calls  this  function. 

~DataObject(  ):  Invokes  save  (  )  and  clears  dynamic  memory 
occupied  by  the  data  object. 

Descendent  Classes  Within  DataObject 

DataOb  ject  is  another  example  of  an  abstract  data  type.  It  contains  the 
format  and  the  methods  used  to  manipulate  the  information  produced  by 
executing  WAVES.  The  methods  are  accessed  through  the  descendent 
classes  MODTRANRe suits,  CSSMResults,  BLIRBResults,  and 
ATMOSRe suits,  as  shown  in  figure  3.  These  classes  are  provided  to  add 
flexibility  in  tailoring  the  output  for  the  needs  of  potential  users.  For 
example,  if  a  future  release  of  CSSM  necessitates  the  addition  of  a  new 
header  variable,  the  variable  could  be  included  entirely  within  the  realm 
of  CSSMResults;  the  remainder  of  the  data  structures  would  continue  to 
be  inherited  from  the  base  class  DataObject.  In  this  manner,  all  the  data 
objects  within  the  toolkit  would  not  have  to  be  rebuilt. 

In  the  current  version  of  the  toolkit,  the  only  added  functionality  pro¬ 
vided  by  the  descendent  classes  is  the  file  name  for  the  object.  When  the 
methods  of  the  descendent  classes  are  called,  program  control  is  immedi¬ 
ately  passed  to  the  base  class. 


3.3  Sample  Program:  Accessing  a  Data  Object 

The  following  program  is  provided  as  an  example  for  accessing  a  data 
object  generated  from  a  WAVES  simulation.  In  this  example,  the  user  is 
attempting  to  extract  the  quantity  "cloud  liquid  water"  from  a  CSSM  data 
object. 

#include  <iostream. h> 

#include  "DataOb ject . h" 
void  main ( ) 

{ 

int  maxEastWest, maxNorthSouth, maxVertical, 

numTimes,  numFreqs; 

float  SWxOrigin,  SWyOrigin,  *levels,  *wavelengths; 

float  *myQuantity; 

CSSMResults  *my_CSSM_output;  //  Declare  the  object 

my_CSSM_output  =  new  CSSMResults (  3122  ) ;  //  Open  experiment 

3122  . 

my_CSSM_output  ->  DO_error->DumpLog ( ) ;  //  Check  for  errors. 

my_CSSM_output  ->  access {); //  Read  the  file. 

//  Obtain  grid  information  (CSSM  uses  only  one  grid  —  number  zero) . 

// 

my_CSSM_output  ->  getGrid(  0,  maxEastWest,  maxNorthSouth, 

maxVertical,  numTimes,  numFreqs, 

SWxOrigin,  SWyOrigin,  levels,  wavelengths 

)  ; 

//  Obtain  a  local  copy  of  the  cloud  liquid  water.  The  mnemonic  needed 
is 

//  "LIQWATER",  which  may  be  determined  by  issuing  the  command: 

//  my_CSSM_output->query ( )  . 

// 
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my_CSSM_output  ->  getQuan  (  "LIQWATER",  myQuantity  ) ; 

// 

//  At  this  point  we  essentially  have  what  we  need:  the  starting 
//  address  of  the  array  containing  the  data.  The  remaining  code 
//  is  used  to  make  a  local  copy  of  the  array  so  we  can  free  up 
//  the  space  used  by  the  data  object. 

float  *liqWater; 

long  arraySize  =  maxEastWest*maxNorthSouth*maxVertical* 
numTimes*numFreqs ; 
liqWater  =  new  float [  arraySize  ] ; 

for  (  int  1=0;  i<arraySize;  i++  )  liqWater [ 1 ] =myQuantity [ 1 ] ; 

//  Close  the  data  object  and  release  its  memory. 

// 

delete  my_CSSM_output ; 

//  Do  some  work. 

// - 

//  End  of  program. 

// - 

delete  []  liqWater; 

} 
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4.  The  Scenario  Object 

The  components  of  the  Scenario  object  are  examined  more  thoroughly 
in  figure  4.  The  purpose  of  this  object  has  been  discussed  previously;  here 
relevant  data  members,  switches,  and  methods  are  reviewed  in  detail. 
Scenario  employs  a  rather  large  number  of  private  data  variables  that 
represent  attributes  common  to  the  entire  suite  of  models.  An  example 
would  be  the  variables  that  reference  the  date  and  time  of  the  simulation, 
referenced  by  the  keywords  DAY,  MONTH,  YEAR,  HOUR,  and  MINUTE. 
Rarely  is  it  necessary  to  define  most  of  these  parameters  (see  the  example 
in  the  section  A  Sample  User  Program  later  in  this  report).  All  have  default 
values  defined  inScenario.C.  the  variables  may  be  accessed  only 
through  the  use  of  keywords  to  maintain  information  hiding.  The  key¬ 
words,  divided  into  groups  for  the  header  variables  and  for  the  scenario 
variables,  are  listed  in  table  1. 

The  Scenario  class  provides  the  following  methods: 

•  Scenario(  int  ):  This  constructor  is  used  to  initialize  an  existing 
scenario.  The  integer  passed  is  the  experiment  identifier.  The  object  is 
opened  READ  ONLY. 

•  Scenario  {  char*  ) :  This  constructor  initializes  an  existing  scenario. 
The  character  constant  is  the  name  of  the  dataset  containing  the  scenario 
attributes.  The  object  is  opened  READ  ONLY. 

•  Scenario!  string  ):  This  constructor  initializes  an  existing  scenario. 
The  string  variable  is  the  name  of  the  dataset  containing  the  scenario 
attributes.  The  object  is  opened  READ  ONLY. 

•  Scenario!  const  strings,  const  strings,  const  strings, 
const  Strings,  const  strings  ):  This  constructor  initializes  a 
new  scenario.  The  arguments  passed  to  the  constructor  are  the  first  five 
elements  of  the  header  data  structure.  The  object  is  opened  WRITE 
ONLY. 

•  SetGlobalAttributes  !  const  ScenarioSettingsS,  const 
floats  ) :  Given  a  keyword  from  the  Scenario  settings  list  and  a  float 
value,  this  function  will  change  the  value  of  a  global  parameter  if  quality- 
control  assertions  are  met. 

•  GetGlobalAttributes !  const  ScenarioSettingsS  ):  Given  a 
keyword  from  the  Scenario  settings  list,  this  function  will  return  a  float 
variable,  representing  the  value  of  the  corresponding  global  parameter. 

•  GetGlobalHeader  !  const  HeaderSettingsS  ):  Given  a  keyword 
from  the  Header  settings  list,  this  function  will  return  a  string  variable 
representing  the  value  of  the  corresponding  global  parameter. 
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Scenario(  int ) 


Scenario 


GetGlobalHeader(  const 
HeaderSettings&) 


Scenario(  char*  ) 


Scenario(  string  ) 


Scenario(  const  string&, 
const  string&,  const 
string&,  const  string&, 
const  string&) 


GetGlobalAttributes( 
const  ScenarioSettings&) 


T 


SetGlobalAttributes( 
const  ScenarioSettings, 
float&) 


GLOBAL  SWITCHES 

BLIRB_MAXX 

BLIRB_MAXY 

BLIRB_MAXZ 

BLIRB_DX 

BLIRB_DY 

BLIRB_DZ 

CSSM_MAXX 

CSSM_MAXY 

CSSM_MAXZ 

CSSM_DX 

CSSM_DY 

CSSM_DZ 

LAT 

LON 

TIMESTEP 

NUMTIMES 

INITIALWAVENUMBER 

FINALWAVENUMBER 

DELTAWAVENUMBER 

SOURCE 

DAY 

MONTH 

YEAR 

HOUR 

MINUTE 

SOURCEZENANGLE 

NUMSTREAMS 

SOURCEAZIMUTH 

MOONPHASE 

STATIONHEIGHT 

AIRTEMP 

RELHUM 

WINDSPEED 

PRESSURE 

VIS 

MAXTEMP 

MINTEMP 

MEANWINDSPEED 

SOILMOIST 

COMP 

SNOW 

SWAG 

VEGCOLOR 

VEGDENSITY 

VEGHEIGHT 

THETA 

GEOWINDSPEED 

INVERSIONHEIGHTISEASN 

BLIRBAERTYPE 

CLOUDSTRUCT 

IMODEL 

SALE 

IHAZE 

lAERSL 

ICLD 

ISOURCE 

SOLAR_ZEN 

SOLAR_AZ 

IFSUN 

ISKY 

_ 

Note:  See  figure  1  for  details  of  Model  and  Ancillary  objects. 

Figure  4.  Details  of  Scenario  class.  Color  coding  as  in  figure  1. 

•  SaveScenario  {  ) :  Saves  the  scenario  settings  to  a  disk  file.  The  de¬ 
structor  automatically  calls  this  function. 

•  ~Scenario(  ):  The  destructor  function  clears  dynamic  memory  gener¬ 
ated  within  Scenario  and  calls  the  SaveScenario  (  )  function. 
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Table  1.  Ke)rwords  defined  within  the  Scenario  class. 


Ke5rwords 

Header  settings 

FILEFLAGS,  JOBTITLE,  EXPID,  EXPDATE, 
EXECUTEDATE 

Scenario  settings 

BLIRB_MAXX,  BLIRB_MAXY,  BLIRB_MAXZ 

BLIRB_DX,  BLIRB_DY,  BLIRB_DZ 

CSSM_MAXX,  CSSM_MAXY,  CSSM_MAXZ 

CSSM_DX,  CSSM_DY,  CSSM_DZ 

EAT,  LON 

TIMESTEP 

NUMTIMES 

INITIALWAVENUMBER, 

FINALWAVENUMBER, 

DELTAWAVENUMBER 

SOURCE 

DAY,MONTH,YEAR,HOUR,MINUTE 

SOURCEZENANGLE 

SOURCEAZIMUTH 

NUMSTREAMS 

MOONPHASE 

STATIONHEIGHT 

AIRTEMP 

RELHUM 

WINDSPEED 

PRESSURE 

VIS 

MAXTEMP,  MINTEMP 

MEANWINDSPEED 

SOILMOIST 

COMP 

SNOW 

VEGCOLOR 

VEGDENSITY 

VEGHEIGHT 


Usage 


Header  attributes,  defined  as  in  the  data  object 

Maximum  size  of  the  BLIRB  simulation  area;  if 
unspecified,  CSSM  grid  defaults  are  used 

Spacing  between  BLIRB  grid  points;  if  unspecified, 
CSSM  grid  defaults  are  used 

Maximum  size  of  the  CSSM  simulation  area;  if 
unspecified,  BLIRB  grid  defaults  are  used 

Spacing  between  CSSM  grid  points;  if  unspecified, 
BLIRB  defaults  are  used 

Geographical  points  of  the  southwest  corner  of  the 
grid  box 

Spacing  between  temporal  grid  points  (s) 

Size  of  temporal  domain 

Variables  specifying  the  frequency  domain,  (cm“^) 

0  =  solar  source,  1  =  lunar  source 

Specification  of  date/ time 

Solar /lunar  zenith  angle 

Solar/lunar  azimuth  angle 

Number  of  streams  for  the  discrete  ordinates 

method  (=  8  for  current  system) 

Phase  angle  of  the  moon 

Altitude  (m)  of  station  above  sea  level 

Air  temperature  (°C  at  2  m) 

Station  relative  humidity  (%) 

Station  wind  speed  (m/s) 

Station  pressure  (mb) 

Visibility  (km) 

Maximum  and  minimum  temperature  for  the 
previous  24-hr  period  (°C) 

Average  wind  speed  over  a  24-hr  period 
Soil  moisture  indicator 
Surface  composition  indicator 
Surface  snow  indicator 
Surface  vegetation  color  indicator 
Surface  vegetation  density  index 
Surface  vegetation  height  indicator 
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Table  1.  (cont'd)  Ke)rwords  defined  within  the  Scenario  class. 


Ke5rwords 

Usage 

GEOWINDSPEED 

Geostrophic  wind  speed 

INVERSIONHEIGHT 

Lowest  inversion  base  height  (m) 

ISEASN 

MODTRAN  season  index 

BLIRBAERTYPE 

BLIRB  boundary  layer  aerosol 

IMODEL 

MODTRAN  atmospheric  model 

SALB 

MODTRAN  albedo 

IHAZE 

MODTRAN  haze  model 
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5.  The  Application-Programmer  Interface 

The  API  represents  the  communication  point  between  WAVES  and  a  user 
program  or  a  client  application  such  as  TAOS.  Within  the  toolkit,  the 
event  handlers  have  the  functional  responsibility  of  an  API.  In  the  present 
version  of  the  toolkit,  the  Event  class  is  provided  as  a  means  of  issuing 
high-level  commands  between  the  user  program  and  the  WAVES  compo¬ 
nents.  Event  also  issues  a  series  of  lower-level  commands  to  the  models 
and  supporting  routines  necessary  to  set  up  and  execute  the  entire  suite. 
Event,  as  discussed  earlier,  is  a  descendant  class  of  Scenario.  The  event 
handler  consists  mostly  of  methods;  there  are  few  data  members,  other 
than  those  inherited  from  Scenario.  The  constructors  for  Event  call  the 
constructors  for  Scenario  without  embellishment,  and  the  arguments 
are  identical.  An  overview  of  the  Event  class  along  with  all  the  available 
methods  is  shown  in  figure  5. 

Three  methods  are  under  construction  that  will  be  used  for  communicat¬ 
ing  with  a  GUI:  attach_GUI (  ),EventLoop(  )  and 
WaitEorEvent  (  ) .  These  will  be  used  to  automatically  sense  the  pres¬ 
ence  of  a  GUI,  and  modify  program  control  accordingly. 

The  most  important  method  within  Event  is  signal  (  ) ,  an  overloaded 
function  that  is  designed  to  send  messages  to  the  model  objects.  It  effec¬ 
tively  hides  the  implementation  of  the  models  and  the  drivers  by  provid¬ 
ing  a  very  specific,  guarded  interface  for  the  user.  It  accepts  up  to  two 
arguments:  a  keyword  and  a  value,  both  of  which  are  quality-checked  for 
erroneous  input.  The  messages  instruct  Scenario  to  create  and  destroy 
model  objects,  to  signal  the  models  to  begin  execution,  or  to  define  local 
parameters.  The  signal  (  )  function  is  the  sole  method  of  interacting 
with  the  model  objects.  This  type  of  restricted  access  is  important,  given 
ARL's  interest  in  coupling  WAVES  with  a  large-scale  simulator.  The  users, 
or  the  simulators  themselves,  should  not  be  allowed  to  assign  invalid 
values  for  any  of  the  input  parameters,  nor  should  they  be  allowed  to 
execute  functions  out  of  sequence.  Each  of  the  messages  supported  by 
the  various  models  also  provides  default  values  for  all  parameters.  This 
ensures  that  undefined  values  will  be  avoided  and  it  provides  an  "escape 
hatch"  for  certain  situations  in  which  erroneous  input  is  encountered. 

The  lists  of  valid  keywords  that  may  be  used  by  the  signaler  are  in  table  2. 
Keywords  for  the  ATMOS  model  are  not  shown  because  that  portion  of 
the  toolkit  remains  under  construction.  The  keywords  are  enumerated 
data  types  defined  in  the  model  classes;  they  are  not  string  arguments 
and,  thus,  quotation  marks  should  not  be  used.  The  model  keywords  are 
always  used  to  define  parameters  local  to  the  model  objects.  Eor  a  de¬ 
scription  of  the  model  keywords,  refer  to  the  appropriate  section  that 
discusses  the  individual  model  objects. 
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Scenario 

Class 

Event(  int ) 


Event(  char*  ) 


Event(  string  ) 


Event(  const  string&,  const 
string&,  const  string&, 
const  string&,  const 
string&) 


signal(  const  I 

modelCommand&, 

action&) 


signal(  const 

MODTRANmnemonic, 

float&) 


signal(  const 

CSSM  mnemonic,  float&) 


signal(  const 
SLAC_mnemonic,  float&) 


signal(  const 

BLIRB  mnemonic,  float&) 


signal(  const 
MODTRANmnemonic) 


1  Event 

j  Application- 
1  Programmer  Interface 

attach_GUi() 

EventLoopO 

^  /•^^ui^vate  vattableT^'. 

WaitForEventO 

Pointers  to  structures 
needed  to  pass  between  y 
model  components 


signai(  const 
CSSM  mnemonic  ) 


signai(  const 
SLAC_mnemonic  ) 


signai(  const 
BLiRB  mnemonic  ) 


signai(  const 
ATMOS_mnemonic  ) 


signai(const 

ATMOS_mnemonic, 

fioat&) 


Figure  5.  Details  of  Event  class.  Event  is  a  descendent  class  from  Scenario  class  and  functions  as 
WAVES  API.  Color  coding  as  in  figure  1. 
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Table  2.  Summary  of  ke)rwords  used  by  signal  (  ) . 


Model 

keywords  Controller  keywords  (also  used  by  model  objects) 


MODTRAN 

GSSM 

SLAG 

BLIRB 

MODTRAN 

IMODEL 

RANDOMSEED 

YEAR 

lAERSL 

UPPERREG_X 

CSSM 

TBOUND 

EGG_NONGUM_l 

MONTH 

MODEL 

LOWERREG_Y 

SLAG 

SALB 

EGG_NONGUM2 

DAY 

IVIS 

UPPERREG_Y 

BLIRB 

lEMSGT 

EGG_NONGUM3 

HOUR 

ISEASN 

LOWERREG_Z 

ATMOS 

ITYPE 

CLOUDTYPE_l 

MINUTE 

IVULCN 

UPPERREG_Z 

MULT 

CLOUDTYPE_2 

LAT 

REGION_MATERIAL  SN 

IHAZE 

GLOUDTYPE_3 

LON 

TBOUND 

ALBEDOJD 

ISEASN 

MAXHEIGHT_1 

lALB 

ALBEDO_VAL 

VIS 

MAXHEIGHT_2 

PRINTLEV 

SFC_TEMP 

WSS 

MAXHEIGHT_3 

LAYER 

ALPHA 

WHH 

MINHEIGHT_1 

TEMPI 

BETA 

HI 

MINHEIGHT_2 

TEMP2 

GAMMA 

H2 

MINHEIGHT_3 

TEMP3 

MATDEEIJD 

IDAY3 

CUMLAYER 

TEMP4 

MATDEE1_DENS 

ISOURG3 

EGG_GUM 

TEMPS 

MATDEE2_ID 

ANGLEM3 

GRIDTYPE 

TEMP6 

MATDEE2_DENS 

IPARM 

NONCUM_LAYERS 

TEMP7 

MATDEE3_ID 

IPH 

BASEMIN 

TEMPS 

MATDEE3_DENS 

IDAY3A1 

HGTMAX 

TEMP9 

GLD 

ISOURC3A1 

TEMPIO 

BND 

OBSLAT 

TEMPll 

WIND 

OBSLON 

TEMP12 

ISG 

PARMl 

TEMP13 

IITL 

PARM2 

LOWAREA_X 

EPSI 

G 

UPPERAREA_X 

IDELTA 

ANGLEM 

LOWAREA_Y 

NPTS 

IVl 

UPPERAREA_Y 

ISN 

IV2 

AREA_SALB 

lAGG 

IDV 

LOWERREG_X 

ISOURC 

ANGLE 

SRCHLT_X 

THSUN 

RANGE 

SRCHLT_Y 

PHSUN 

IVULCN 

SRCHLT  Z 

lESUN 

SRCHLT_THETA  ISKY 
SRCHLT_AZIMUTH  IFTRN 
SRCHLT_ENERGY  PANGL 
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Table  2.  (cont'd)  Summary  of  ke3rwords  used  by  signal  (  ) . 


Model 

keywords 

Controller  keywords  (also  used  by  model  objects) 

MODTRAN 

CSSM 

SLAC 

BLIRB 

SRCHLT_TEMP 

XJNTERVALS 

SRCHLT_DIAM 

YJNTERVALS 

VI 

ZJNTERVALS 

V2 

X_UPPERBOUND 

DV 

Y_UPPERBOUND 

Z_UPPERBOUND 

The  signaler  may  be  called  in  one  of  three  ways: 

•  signal!  model_k;eyword,  value  ):  Initializes  parameters  within 
model  objects.  The  parameters  are  referenced  by  model_k;eyword  and 
set  to  value,  a  float  variable,  pending  quality-control  assertions. 

•  signal!  controller_k;eyword,  command  ):  Controls  a  model 
object.  The  controller_k;eyword  (see  table  2)  references  a  specific 
model.  Command  has  one  of  the  following  values:  CREATE,  INVOKE,  or 
DESTROY.  A  dynamic  instance  of  a  model  is  generated  with  CREATE; 
hence,  signal  !MODTRAN,  CREATE)  would  instantiate  MODTRAN  and 
call  its  constructor.  The  DESTROY  command  would  likewise  invoke  the 
destructor,  returning  dynamic  arrays  to  the  heap;  further  references  to 
that  instance  of  the  MODTRAN  object  are  not  possible  after  this  com¬ 
mand  is  issued.  INVOKE  is  used  to  execute  a  model. 

•  signal!  controller_keyword  ):  Returns  the  value  of  a  parameter 
as  a  float  variable. 

The  present  event  handler  implementation  is  in  the  file  Event .  C. 
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6.  The  Model  Objects 

The  model  objects  are  wrapped  about  the  "core"  science  elements  of 
WAVES.  They  provide  communication  between  the  toolkit  and  the  older 
Fortran  modules,  control  access  to  the  model  drivers,  and  serve  as  a 
platform  for  dynamic  memory  allocation.  The  software  design  of  the 
toolkit  leaves  much  of  the  legacy  model  code  unchanged.  Required  data 
structures  are  passed  from  the  wrappers  directly  into  the  model  drivers. 
Within  the  wrappers,  quality  checks  are  performed  on  the  input  param¬ 
eters  before  model  execution.  Because  the  wrappers  are  written  in  C-i-i-, 
dynamic  allocation  of  large  arrays  used  by  the  Fortran  code  is  possible.  In 
such  cases,  memory  addresses  are  passed  to  the  model  drivers,  replacing 
over  dimensioned,  static  arrays. 

The  model  objects  are  designed  to  operate  independently  outside  the 
WAVES  Toolkit.  Each  object  is  a  complete  instance  of  a  particular  model. 
The  Scenario  class  and  the  event  handler  use  these  objects,  by  way  of 
containment,  to  formulate  a  WAVES  simulation.  In  the  discussion  that 
follows,  the  model  objects  are  described  as  individual,  external  objects. 

6.1  MODTRAN 

MODTRAN  is  available  through  the  Air  Force  Geophysics  Laboratory 
(AFGL),  Hanscom  Air  Force  Base,  Massachusetts  (http:// 
www._vsbm.plh.af.mil/soft/modtran.html).’*'  WAVES  currently  uses 
MODTRAN  version  3.5.  For  documents  describing  the  scientific  aspects 
of  MODTRAN,  the  reader  is  referred  to  the  many  publications  provided 
by  AFGL.  It  is  not  the  intention  of  ARE  to  redistribute  MODTRAN  via 
WAVES.  Rather,  a  restricted  implementation  is  being  developed  for  the 
toolkit  in  which  only  the  required  information  from  MODTRAN  is  re¬ 
trieved.  This  includes  the  incoming  solar  irradiance  at  the  top  of  the 
WAVES  volume,  the  path  scattered  radiance  within  the  volume,  and  the 
molecular  transmission  for  each  layer  within  the  volume.  Through  the 
techniques  of  information  hiding,  a  restricted  version  of  MODTRAN  is 
developed  readily. 

Much  of  the  functionality  of  the  MODTRAN  interface  is  designed  to 
replace  the  antiquated  1/ O  procedures  of  the  original  driver.  These 
procedures  are  discussed  in  detail  by  Kneizys  et  al  [7],  and  in  later  up¬ 
dates  to  that  document.  The  standard  version  of  MODTRAN  requires  the 
user  to  select  input  parameters  by  way  of  an  input  dataset;  output  is 
routed  to  a  series  of  other  datasets.  Input  parameters  are  required  to 
appear  in  a  specific,  column-oriented  format  known  as  a  card  image.  The 
WAVES  software  design  targets  removal  of  the  I/O  system  used  by 
MODTRAN,  and  replaces  it  with  methods  for  initializing  and  retrieving 
private  data  members.  This  effort  will  allow  MODTRAN  to  easily  be 


*This  is  the  current  URL  site.  However,  the  URL  may  change  as  modifications  are  made  to  the  software.  A 
point  of  contact  for  MODTRAN  can  be  reached  at  781-377-2335  or  DSN  478-2335. 
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coupled  with  the  WAVES  Toolkit  and  subsequently  to  a  simulator.  The 
model  output  that  is  required  by  WAVES  is  passed  back  directly  to  the 
wrapper.  The  toolkit  interfaces  to  the  Eortran  subroutine  DRIVER.  All  the 
input  structures  are  passed  into  the  model  at  this  point.  The  required 
output  is  also  passed  back  to  the  wrapper  through  DRIVER. 

An  overview  of  the  MODTRAN  model  object  is  displayed  in  figure  6.  The 
keywords  used  by  the  MODTRAN  object  for  data  initialization  are  shown 
in  table  3,  along  with  the  variable  names  and  a  brief  description.  Note 
that  some  of  the  parameters  have  global  definition  in  Scenario. 

Through  the  event  handler,  those  definitions  will  assign  similar  values 
locally;  no  additional  action  is  required.  If  necessary,  the  model  object 
keywords  may  be  used  to  override  the  global  parameters  from  the  event 
handler. 

The  following  methods  are  provided: 

MODTRAN  (  ) :  The  constructor  function  initializes  all  of  MODTRAN's 
input  parameters,  including  those  not  implemented,  using  default  values 
(see  the  section  on  MODTRAN.C). 

initialize  (  MODTRAN_mnemonic,  float ):  Initializes  parameters 
within  MODTRAN.  The  parameters  are  referenced  by  the  mnemonic  and 
assigned  to  value,  a  float  variable,  pending  quality-control  assertions. 
This  function  is  called  directly  by  the  signal  (  )  function  in  the  event 
handler. 

initialize  (  MODTRAN_mnemonic ) :  Returns  the  value  of  a  parameter 
as  a  float  variable. 

invoke  (  float*,  float*,  int*,  float* ):  Executes  MODTRAN. 
Pointers  to  the  following  four  arrays  are  used  (the  user  must  supply 
dynamic  space  for  these  variables  accordingly;  see  the  section  A  Sample 
Implementation  of  Event  later  in  this  report).  These  arrays  are  later  saved  in 
the  MODTRAN  data  object. 

-  A  float  array  containing  the  solar  irradiances. 

-  A  float  array  containing  the  path  scattered  radiances. 

-  An  integer  array  containing  the  wavenumbers  used  by  MODTRAN. 

-  A  float  array  containing  the  molecular  transmission  values  for  each 
level. 

DayOfYear (  const  floats,  const  floats,  const  floats,  ): 

Returns  the  day  of  the  year  given  a  year,  month,  and  day. 


MODTRANQ 


initialize( 

MODTRAN_mnemonic&, 
float ) 

initialize( 

MODTRAN_ninemonic&  ) 

invoke(float*,  float*,  int*, 

float* ) 


MODTRAN 

Access-controlled  interface 


cardi 

card1_other 

cardi  A 

cardi  A_other 

card2 

card2A 

card2A_other 

card2B 

card2C 

card2C1 


ERROR 

OBJECT 


DayOfYear(  float*,  float*, 
float* ) 


card2Cch 

card2C2 

card2CX 

card2C3 


MODTRAN  SWITCHES 


IMODEL 

TBOUND  SALB 

lEMSCT 

ITYPE 

MULT 

IHAZE 

ISEASN 

VIS 

WSS 

WHH 

HI 

H2 

IDAY3 

IS0URC30BSLAT 

OBSLON  PARM1 

PARM2 

G 

ANGLEM 

RANGE 

IV1 

IVULCN 

IV2 

ANGLE 

card2D 

card2D1 

card2D1ch 

card2D2 

cards 

cardSAI 

card3A2 

cardSBI 

card3B2 

card4 


FORTRAN  CODE 


SUBROUTINE  DRIVER  (carcU,  card1_other, 
cardi  A,  cardi  A_other,card2,  card2A, 
card2A_other,card2B,  card2C,  card2C1  ,char, 
card2Cch,  card2C2,card2CX,card2C3, 
card2D,card2D1  ,card2D1ch,  card2D2, 
cards, cardSAI ,card3A2,  cardSBI,  card3B2, 
card4,  REAL,  REAL,  INTEGER,  REAL  ) 


Figure  6.  Details  of  MODTRAN  class.  Color  coding  as  in  figure  1. 
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Table  3.  Switch  settings  for  MODTRAN. 


Ke5rword 

(MODTRAN_mnemonic) 

Private  data  member 

Description 

IMODEL 

inputl  iModel  Atmosphere 

Model  atmosphere  t5q)e 

TBOUND 

inputl  .f  TBound 

Ground  surface  temperature 

SALE 

inputl  iSfc  Albedo 

Surface  albedo 

lEMSCT 

inputl  .f  ExecMode 

Execution  mode 

ITYPE 

inputl  i  PathType 

Path  type  control 

MULT 

inputlo.fMultScat 

Multiple  scattering  option 

IHAZE 

input2.fHaze 

Bound  layer  haze  model 

ISEASN 

input2.fSeason 

Seasonal  aerosol 

VIS 

input2.fVisibility 

Boundary  layer  visibility 

WSS 

input2.fWindSpeed 

Station  height  wind  speed 

WHH 

mput2.fAvgWindSpeed 

Daily  mean  surface  wind  speed 

HI 

input3  .f  Initial  Alt 

Max  Z  dimension 

H2 

input3  .f  Pinal  Alt 

Pinal  altitude 

IDAY3 

input3  i  DayOfYear 

Julian  date 

ISOURC3 

input3  i  ExtrSource 

Solar /lunar  source 

ANGLEM3 

input3  .f  PhAngleMoon 

Moon  phase  angle 

IPARM 

input3  A1 .  iGontrol 

Input  control 

IPH 

input3Al  .iHGPhasePunc 

Henyey-Greenstein  phase  function 

IDAY3A1 

input3Al  .iDayOfYear 

Julian  date 

ISOURC3A1 

input3  A1 .  iExtrSource 

Extraterrestrial  source 

OBSLAT 

input3A2.fObsLat 

Observer  latitude 

OBSLON 

input3A2.fObsLon 

Observer  longitude 

PARMl 

mput3A2.fAzAngle 

Azimuth  angle 

PARM2 

input3A2.fSunZen  Angle 

Solar  zenith  angle 

G 

input3A2.fAssymPactor 

HG  asymmetry  factor 

ANGLEM 

input3A2.fMoonPhAngle 

Limar  phase  angle 

IVl 

input4.iInitPreqWN 

Minimum  spectral  wave  number 

IV2 

input4.iPinalPreqWN 

Maximum  spectral  wave  number 

IDV 

input4.iPreqInc 

Spectral  bandwidth 

ANGLE 

input3.f Angle 

Apparent  solar  or  lunar  zenith  angle  from 
final  altitude  (LookZ) 

RANGE 

input3.f  Range 

Range  (path  length) 

IVULCN 

input2.Volcanic 

Stratospheric  profile 
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6.2 


CSSM 


The  implementation  for  CSSM  is  similar  to  that  of  MODTRAN,  except 
that  here  a  full  implementation  is  necessary.  An  overview  of  the  model 
object  is  shown  in  figure  7.  The  keywords  used  by  the  CSSM  object  for 
data  initialization  are  shown  in  table  4,  along  with  the  variable  names  and 
a  brief  description.  The  interface  point  between  the  wrapper  and  the 
model  is  the  Fortran  subroutine  CLOUD.  Nearly  all  the  parameters 
required  to  set  up  the  CSSM  grid  are  passed  through  this  interface.  The 
output  array  containing  the  liquid  water  quantity  is  returned. 

The  following  methods  are  provided: 

•  CSSM(  const  floats,  const  floats,  const  floats,  const 
floats,  const  floats  ):  The  constructor  function  initializes  all  the 
CSSM  input  parameters.  Values  passed  to  the  constructor  are  the  maxi¬ 
mum  X  and  y  dimensions,  and  the  grid  spacing  for  the  x,  y,  and  z  dimen¬ 
sions. 

•  initialize  (  CSSM_mnemonic,  float ):  Initializes  parameters 
within  CSSM.  The  parameters  are  referenced  by  the  mnemonic  and 
assigned  to  value,  a  float  variable,  pending  quality-control  assertions. 
This  function  is  called  directly  by  the  signal  (  )  function  in  the  event 
handler. 

•  initialize  {  CSSM_mnemonic) :  Returns  the  value  of  a  parameter  as  a 
float  variable. 

•  invoke  {  float*  ):  Executes  CSSM.  The  user  must  allocate  space  for 
the  array  referenced,  which  contains  the  liquid  water  content  at  each  grid 
point.  This  information  is  later  saved  in  the  CSSM  data  object. 
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CSSM 


cssm(const  float&,  const 
float&,  const  float&, 
const  float&,  const& 


initialize( 

CSSM_mnemonic&,  float  ) 


initialize( 

CSSM_mnemonic&  ) 


ERROR 

OBJECT 


invoke(  float* ) 


/  numlay,  iseed, 

/ itype[LMAX],  ix,  iy, 

/  igrid,  numsnd, 

itmax,  ifile,  Icum; 
cover[LMAX],  tres, 
base[LMAX], 
top[LMAX],  xmax,  ymax, 
xres,  yres,  yres1 ,  zres, 
ps[ISMAX],  zs[ISMAX], 
ts[ISMAX],  tds[ISMAX], 

.  wxs[ISMAX], 

\wys[ISMAX],  basmin,  j 
\  hgtmax,  zmax;  / 


CSSM  SWITCHES 


RANDOMSEED 

FCC_NONCUM_1 

CLOUDTYPEJ 

CLOUDTYPEJ 

MAXHEIGHTJ 

CUMLAYER 


FCC_NONCUM_1 
FCC_NONCUM_1 
CLOUDTYPEJ 
MAXHEIGHTJ 
MAXHEIGHTJ 
FCC  CUM  GRIDTYPE 


FORTRAN  CODE 


SUBROUTINE  CLOUD  (integer,  integer, 
reai,  integer,  reai,  reai,  real,  real,  real,  real, 
real,  real,  integer,  character,  integer,  integer, 
integer,  integer,  real,  integer,  real, 
real,  integer,  real,  real,  real,  real,  real,  real, 
integer,  integer,  integer,  real) 


Figure  7.  Details  of  CSSM  class.  Color  coding  as  in  figure  1. 


28 


Table  4.  Switch  settings  for  CSSM. 

Ke5rword 

(CSSM_mnemonic)  Private  data  member  Description 

Random  number  initializer 


RANDOMSEED 

Iseed 

ECC_NONCUM_l 

cover[0] 

ECC_NONCUM_2 

cover[l] 

ECC_NONCUM_3 

cover[2] 

CLOUDTYPE_l 

itype[0] 

CLOUDTYPE_2 

itype[l] 

CLOUDTYPE_3 

itype[2] 

MAXHEIGHT_1 

top[0] 

MAXHEIGHT_2 

top[l] 

MAXHEIGHT_3 

top[2] 

MINHEIGHT_1 

base[0] 

MINHEIGHT_2 

base[l] 

MINHEIGHT_3 

base[2] 

CUMLAYER 

Icum 

ECC_GUM 

cover[numlay] 

GRIDTYPE 

igrid 

NONGUM_LAYERS 

numlay 

BASEMIN 

basmin 

HGTMAX 

hgtmax 

Fractional  cloud  coverage,  noncumulus  layer  1 

Fractional  cloud  coverage,  noncumulus  layer  2 

Fractional  cloud  coverage,  noncumulus  layer  3 

Cloud  type,  layer  1 

Cloud  type,  layer  2 

Cloud  type,  layer  3 

Cloud  top,  layer  1 

Cloud  top,  layer  2 

Cloud  top,  layer  3 

Cloud  bottom,  layer  1 

Cloud  bottom,  layer  2 

Cloud  bottom,  layer  3 

Cumulus  present? 

Fractional  cloud  coverage,  cumulus  layer 
Grid  t5^e  (0  =  Cartesian,  1  =  cylindrical) 
Number  of  noncumulus  cloud  layers 
Cloud  base  minimum  height 
Cloud  top  maximum  height 
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6.3  BLIRB 


A  full  implementation  of  BLIRB  is  designed  for  use  in  the  toolkit.  A  layout 
of  the  BLIRB  model  object  is  shown  in  figure  8.  The  interface  point  be¬ 
tween  the  wrapper  and  BLIRB  is  Fortran  subroutine  EOEXEC.  All  the 
input  structures  are  passed  through  this  point.  A  list  of  the  valid  key¬ 
words  along  with  the  corresponding  names  for  the  private  data  members 
is  shown  in  table  5.  Zardecki  [2]  provides  a  detailed  description  of  these 
parameters. 

The  output  from  BLIRB  is  currently  being  saved  to  the  file  OutEiles/ 
GRID.ASC.  Conversion  routines  are  available  outside  of  the  toolkit  to 
convert  this  file  into  a  BLIRB  data  object.  In  the  future,  a  function  to 
generate  a  linked  list  of  output  quantities  will  be  available  and  will  be 
called  by  BLIRB.  The  purpose  of  this  function  is  to  allow  users  to  write 
out  any  quantity  necessary,  without  having  to  worry  about  storage  space, 
data  formats,  or  ordering.  The  linked  list  will  generate  an  internal  file  that 
will  be  read  by  the  toolkit  wrapper;  subsequently,  the  toolkit  will  call  a 
function  to  generate  a  BLIRB  data  object. 

The  following  methods  are  provided: 

•  blirb{  const  floats,  const  floats,  const  floats,  const 
floats,  const  floats,  const  floats,  const  floats, 
const  floats  ):  The  constructor  function  initializes  all  the  BLIRB 
input  parameters.  Values  passed  to  the  constructor  are  the  size  and 
resolution  of  the  temporal  dimension,  the  maximum  x,  y,  and  z  dimen¬ 
sions,  and  the  grid  spacing  for  the  x,  y,  and  z  dimensions. 

•  initialize  (  blirb_mnemonic,  float ):  Initializes  parameters 
within  BLIRB.  The  parameters  are  referenced  by  the  mnemonic  and 
assigned  to  value,  a  float  variable,  pending  quality-control  assertions. 
This  function  is  called  directly  by  the  signal  (  )  function  in  the  event 
handler. 

•  initialize  (  blirb_mnemonic,  int,  float ):  Initializes  multidi¬ 
mensional  parameters  within  BLIRB.  The  parameters  are  referenced  by 
the  rrmemonic  and  assigned  to  value,  a  float  variable,  pending  quality- 
control  assertions. 

•  initialize  (  BLIRB_mnemonic) :  Returns  the  value  of  a  parameter  as 
a  float  variable. 

•  invoke  (  MODTRANResults*,  CSSMResults*  ):  Executes  BLIRB. 

The  user  must  allocate  space  for  the  two  data  objects  required.  The  output 
is  not  passed  through  this  interface;  an  internal  file  is  generated  that  is 
later  read  by  either  the  event  handler  or  the  BLIRB  model  object,  and  is 
converted  into  a  BLIRB  data  object. 
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blirb(const  float&,  const 
float&,  const  float&, 
const  float&,  const 
float&,  const  float&, 
const  float&,  const 
float&) 

initialize( 

blirb_mnemonic&,  float  ) 
initialize( 

blirb_mnemonic&,  int, 
float ) 

initialize( 

blirb_mnemonic&  ) 
lnvoke( 

MODTRANResults*, 
CSSMResults* ) 


BLIRB 


ERROR 

OBJECT 


mdl1 

mdl2 

mdl3_4 

albedo 

regn 

mesx 

mesy 

mesz 

area 

material 

clouds 

domd 

solar 

searchlight 

wavn 


BLIRB  SWITCHES 

See  table  2  and  Zardecki  (1996) 


FORTRAN  CODE 

SUBROUTINE  EOEXEC  (REAL,  REAL,  mdll, 
mdl2,  mdl3_4,  area,  regn,  mesx, mesy, 
mesz, albedo, material,  clouds,  domd,  solar, 
searchlight,wavn,  REAL,  REAL,  REAL, 
REAUREAL,  REAL,REAL,  REAL,  REAL,REAL, 
REAL,  REAL,  REAL) 


LINKED  LIST 
STRUCTURE  for 
OUTPUT 
OUANTITIES 


Internal  volatile 
output  file 


Figure  8.  Details  of  BLIRB  class.  Color  coding  as  in  figure  1. 
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Table  5.  Switch 
settings  for  BLIRB. 


Ke5rword 

(BLIRB_mnemonic) 

Private  data  member 

lAERSL 

input_mdll  .iaersl 

MODEL 

input_mdll  .model 

IVIS 

input_mdll  .ivis 

ISEASN 

input_mdll  .iseasn 

IVULCN 

input_mdll  .ivulcn 

SN 

input_mdl2.sn 

TBOUND 

input_mdl2.tbound 

lALB 

input_mdl2.ialb 

PRINTLEV 

input_mdl2.ip 

LAYER 

input_mdl2.ilyr 

TEMPI 

input_mdl3_4.temp[0] 

TEMP2 

input_mdl3_4.temp[l] 

TEMPS 

input_mdl3_4.temp[2] 

TEMP4 

input_mdl3_4 .  temp  [3  ] 

TEMPS 

input_mdl3_4.temp[4] 

TEMP6 

input_mdl3_4 .  temp  [5  ] 

TEMP7 

input_mdl3_4.temp[6] 

TEMPS 

input_mdl3_4.temp[7] 

TEMP9 

input_mdl3_4.temp[8] 

TEMPIO 

input_mdl3_4.temp[9] 

TEMPll 

input_mdl3_4.temp[10] 

TEMP12 

input_mdl3_4.temp[ll] 

TEMP13 

input_mdl3_4.temp[12] 

XJNTERVALS 

input_mesx.mhx 

YJNTERVALS 

input_mesy.mhy 

ZJNTERVALS 

input_mesz  .mhz 

X_UPPERBOUND 

input_mesx.xms 

Y_UPPERBOUND 

input_mesy.yms 

Z_UPPERBOUND 

input_mesz.zms 

CLD 

input_clouds.icld 

BND 

input_clouds.ibnd 

WIND 

input_clouds.wind 

ISC 

input_domd.isc 

IITL 

input_domd.iitl 

EPSI 

input_domd.epsi 

IDELTA 

input_domd.idelta 

NETS 

input_domd.npts 

ISN 

input_domd.isn 

lACC 

input_domd.iacc 

ISOURC 

input_solar.isourc 

THSUN 

input_solar.thsun 

PHSUN 

input_solar.phsun 

IPSUN 

input_solar.ifsun 

ISKY 

input_solar.isky 

lETRN 

input_solar.iftrn 

PANGL 

input_solar.pangl 

SRCHLT_X 

input_searchlight.xsrch 

SRCHLT_Y 

input_searchlight.ysrch 
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Table  5.  (cont'd) 
Switch  settings  for 
BLIRB. 


Ke5rword 

(BLIRB_mnemonic) 

Private  data  member 

SRCHLT_Z 

input_searchlight.zsrch 

SRCHLT_THETA 

Input_searchlight.thsrch 

SRCHLT_AZIMUTH 

input_searchlight.azsrch 

SRCHLT_ENERGY 

input_searchlight.psrch 

SRCHLT_TEMP 

input_searchlight.tmsrch 

SRCHLT_DIAM 

input_searchlight.sdiam 

VI 

input_wavn.vl 

V2 

input_wavn.v2 

DV 

input_wavn.dv 

LOWAREA_X 

input_area[index]  .alx 

UPPERAREA_X 

input_area[index].ahx 

LOWAREA_Y 

input_area[index]  .aly 

UPPERAREA_Y 

input_area[index].ahy 

AREA_SALB 

input_area[index]  iamtl 

LOWERREG_X 

input_regn[index].rlx 

UPPERREG_X 

input_regn[index].rhx 

LOWERREG_Y 

input_regn[index].rly 

UPPERREG_Y 

input_regn[index].rhy 

LOWERREG_Z 

input_regn[index].rlz 

UPPERREG_Z 

input_regn[index].rhz 

REGION_MATERIAL 

input_regn[index].izmtl 

ALBEDOJD 

input_albedo  [index]  .lalb 

ALBEDO_VAL 

input_albedo  [index] .  f  alb 

SPG_TEMP 

input_albedo  [index] .  talb 

ALPHA 

input_albedo  [index] .  alpha 

BETA 

input_albedo  [index]  .beta 

GAMMA 

input_albedo  [index]  .gamma 

MATDEEIJD 

input_material[index]  .Imtll 

MATDEE1_DENS 

input_material[index]  .wmtll 

MATDEE2_ID 

input_material[index]  .lmtl2 

MATDEE2_DENS 

input_material[index]  .wmtl2 

MATDEE3_ID 

input_material[index]  .lmtl3 

MATDEE3_DENS 

input_material[index]  .wmtl3 

33 


7.  Programming  Examples 

The  following  examples  are  provided  to  aid  the  software  developer.  These 
files  are  available  on  the  development  computer  at  ART.  (Contact  Alan 
Wetmore  at  ART  for  assistance  on  development  samples.) 

7.1  A  Sample  Implementation  of  Event 


#include  <iostreain .  h> 
#include  <stdlib.h> 
#include  <assert.h> 
#include  "Event. h" 


Event  : :  Event (  const 

Strings 

sReqFileFlags , 

const 

Strings 

sReqTitle, 

const 

Strings 

sReqExpID, 

const 

Strings 

sReqExpDate, 

const 

Strings 

sReqExecuteDate 

Scenario ( 


{ 

cout  <<  "Event  constructor  has  been  invoked."  <<  endl; 

} 


sReqFileFlags , 
sReqTitle, 
sReqExpID, 
sReqExpDate, 
sReqExecuteDate  ) 


int  Event  : :  signal (  const  model Commands  command,  const  modelActionS  action  ) 

{ 

switch  (  command  )  { 


case  MODTRAN: 


{ 

switch  (  action  )  { 

case  CREATE: 

{ 

if  (  MODTRANActive  )  { 

Scenario_error->LogError ( 3 , " Severity=CAUTION  MODTRAN 

already  exists."); 

return  (-999) ; 

} 

MODTRANObj  =  new  MODTRAN; 

if  (  ! f inalWavenumber_def ined  | |  ! initialWavenumber_def ined 

I  I  !  deltaWavenumber_def ined  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  Wavenumber 
parms  undefined."  <<  endl; 

} 
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int  numFrequencies  =  (int) ( ( f inalWavenumber- 
initialWavenumber ) /deltaWavenumber ) ; 

int  numModelRuns  =  (int)  (nuin_streams/2  +  2); 

float  *wavelengths ; 

wavelengths  =  new  float [  (int) (f inalWavenumber- 
initialWavenumber) +50  ]; 

for  (  int  k=0;  k<nuinFrequencies ;  k++  )  { 

wavelengths [k]  =  initialWavenumber  +  deltaWavenumber*k; 

} 


MODTRANOutput  =  new  MODTRANResults ( 

GetGlobalHeader ( 
GetGlobalHeader ( 
GetGlobalHeader ( 
GetGlobalHeader ( 
GetGlobalHeader ( 

2 , 3*numModelRuns  ); 


FILEFLAGS  ) , 
JOBTITLE  ) , 
EXPID  ) , 
EXPDATE  ) , 
EXECUTEDATE 


// 

// 

// 


Set  up  the  first  grid  for  the  output  object. 

(The  second  grid  will  be  set  up  at  the  INVOKE  stage) . 


float  ^levels; 
levels  =  new  float [1]; 
levels [ 0 ]  =  0 .  ; 

MODTRANOutput  ->  putGrid (  0,  1,  1,  1,  1,  numFrequencies, 

0.,  0.,  levels,  wavelengths  ) ; 


delete  []  wavelengths; 
delete  []  levels; 

MODTRANCount  =  0; 
assert (  MODTRANObj  ) ; 

MODTRANActive=TRUE; 

//  Bring  in  the  global  (scenario)  environment;  set  switches  accordingly. 

//  - 

MODTRANObj->  initialize  (  MODTRAN :  : IMODEL, 

GetGlobalAttributes (  ( ScenarioSettings ) IMODEL)  ); 

MODTRANObj->  initialize  (  MODTRAN :: IHAZE, 

GetGlobalAttributes (  (ScenarioSettings) IHAZE)  ) ; 
MODTRANObj->  initialize (  MODTRAN :: ISEASN, 

GetGlobalAttributes (  (ScenarioSettings) ISEASN)  ); 
MODTRANObj->  initialize  (  MODTRAN:  :VIS, 

GetGlobalAttributes (  (ScenarioSettings) VIS)  ); 

if  (  GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXZ  )  >8.5 

)  { 

MODTRANObj->  initialize (  MODTRAN: :H1,  12.); 

}  else  { 

MODTRANObj->  initialize (  MODTRAN: :H1,  5.); 
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MODTRANObj->  initialize  (  MODTRAN :: ANGLE, 

GetGlobalAttributes (  ( ScenarioSettings ) SOURCEZENANGLE) 

if  (  day_defined  &&  month_def ined  &&  year_defined  )  { 


tributes ( 


cout  <<  "Processing  for  date:  "  << 

MODTRANOb j->DayOfYear (GetGlobalAtti 
( ScenarioSettings ) YEAR  ), 

GetGlobalAttributes (  (ScenarioSettings) MONTH) 
GetGlobalAttributes (  ( ScenarioSettings ) DAY  ) 

MODTRANObj->  initialize  (  MODTRAN :: IDAY3, 

MODTRANOb j->  DayOfYear ( 

GetGlobalAttributes (  ( ScenarioSettings ) YEAR  ) 

GetGlobalAttributes  (  ( ScenarioSett ’ 

4—  1  -^1  7\  4^  4*  •v'  1  T  4—  /  / 


V  V‘-^^^^^ciJ--L'^oc:uuingS)  MONTH  ) 
GetGlobalAttributes (  {i 


}  else  { 

cout  «  "WARNING:  Dat 


Ot^CilClJ-X'^OCUl _ Liiyo  ]  L'i-KJ  IN  J.  i  i  ; 

ScenarioSettings ) DAY  ) 
e  is  undefined."  <<  endl; 


cout  <<  "SOURCE  IS 
( ScenarioSettings ) SOURCE  ); 

MODTRANObj->  initialize 
Get Global At tribute 
MODTRANObj->  initialize 
Get Global At tribute 
MODTRANObj->  initialize 
Get Global At tribute 


<<  GetGlobalAttributes ( 


(  MODTRAN: : IS0URC3, 
s(  (ScenarioSettings) SOURCE)  )  ; 

(  MODTRAN: : IS0URC3A1, 
s(  (ScenarioSettings) SOURCE)  )  ; 

(  MODTRAN: : IVl, 

s (  (ScenarioSettings) INITIALWAVENUMBER) 


MODTRANObj->  initialize 
Get Global At tribute 


(  MODTRAN: : IV2, 

s  (  (ScenarioSettings) FINALWAVENUMBER) 


MODTRANObj->  initialize 
Get Global At tribute 


(  MODTRAN: : IDV, 

s  (  (ScenarioSettings) DELTAWAVENUMBER) 


break; 


} 


case  DESTROY: 

{ 

if  (  IMODTRANActive  )  { 

ErrorLog(4,  "Level=Warning,  Source=signal ,  Message=MODTRAN 
already  destroyed"); 

}  else  { 

cout  <<  "  Destroying  MODTRAN  Object....  final  MODTRAN 
results  follow."  <<  endl; 

delete  MODTRANOutput ; 

delete  MODTRANOb j ; 

MODTRANActive  =  FALSE; 


break; 
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0; 


case  INVOKE: 

{ 

static  int  iGridActive  = 
if  (  IMODTRANActive  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  No  active 
MODTRAN  object  detected."); 


assert  (  MODTRANCount  <  MAXINVOKE  )  ; 
string  quanID; 

int  numFrequencies  =  (int) ( ( f inalWavenumber- 
initialWavenumber ) /deltaWavenumber ) ; 

int  iFreqSpan; 


50; 


Initialize 

0.; 


iFreqSpan  =  (int) ( f inalWavenumber-initialWavenumber )  + 

f TransSolarIrr  =  new  float [  numFrequencies  +  1  ]  ; 

f PathScattRad  =  new  float [  numFrequencies  +  1]; 

f_Dtau  =  new  float [  MAX_MODT_LEVELS  *  iFreqSpan  ] ; 

i_calc_WN  =  new  int [  iFreqSpan  ]  ; 

for  (  int  i=0;  i<iFreqSpan;  i++  )  i_calc_WN[i]  =  -999;  // 

for  (  i=0;  i< (MAX_MODT_LEVELS  *  iFreqSpan);  i++  )  f_Dtau[i] 


MODTRANObj  ->  invoke (  fTransSolarIrr,  fPathScattRad, 
i_calc_WN,  f_Dtau  ) ; 


//  The  two-dimensional  array  f_Dtau  must  be  turned  on  its  side  for  use 
//  in  the  MODTRAN  Data  Object. 


float  ^reorder; 
int  count=0; 

reorder  =  new  float [  MAX_MODT_LEVELS  *  iFreqSpan  ] ; 
for  (  int  j=0;  j<MAX_MODT_LEVELS;  j++  )  { 

for  (  i=0;  i<iFreqSpan;  i++  )  { 

reorder [count++]  =  f_Dtau [  MAX_MODT_LEVELS*i  +  j  ]; 

} 

} 

f or (  i=0 ; i< (count-1 ); i++  )  f_Dtau[i]  =  reorder [i]; 
delete  []  reorder; 

float  *wavelengths ,  *levels; 
wavelengths  =  new  float [  iFreqSpan  ] ; 
levels  =  new  float [  MAX_MODT_LEVELS  ] ; 

for  (  i=0;  i<iFreqSpan;  i++  )  wavelengths [ i ]  = 

(float ) i_calc_WN [ i ]  ; 

for  (  i=0;  i<MAX_MODT_LEVELS ;  i++  )  levels [i]  =  (float) i; 
if  (  ! iGridActive  )  { 

cout  <<  "Now  activating  GRID  1  from  MODTRAN."  <<  endl; 
MODTRANOutput  ->  putGrid (  1,  1,  1,  MAX_MODT_LEVELS ,  1, 


iFreqSpan, 


0.,  0.,  levels,  wavelengths  ); 


iGridActive 


1; 


} 

quanID  =  "SOLARIRR"; 
quanID  +=  MODTRANCount  ; 

MODTRANOutput  ->  putQuan (  quanID, "Solar  irradiance  at  top  of 
box" , 0 , fXransSolarlrr  ); 

cout  <<  "PATHRAD  :  first  4  elements:"  <<  endl; 

for  (  int  k:=0  ;  k:<4  ;  k:++  )  cout<<fPathScattRad  [k]  <<endl; 
quanID  =  "PATHRAD"; 
quanID  +=  MODTRANCount; 

MODTRANOutput  ->  putQuan (  quanID, "Skylight  (diffuse) 
radiation" , 0 , fPathScattRad  ); 

if  (  iFreqSpan  >  0  )  { 

quanID  =  "DELTATAU"; 
quanID  +=  MODTRANCount; 

MODTRANOutput  ->  putQuan (  quanID, "Layer 
transmission" , I , f_Dtau  ); 

} 

MODTRANCount++; 

if  (  MODTRANCount  >=  ( ( int ) num_streams/2  +  2)  ) 

modelHistory . MODTRAN=TRUE ; 


delete 

[] 

fTransSolarIrr; 

delete 

[] 

fPathScattRad; 

delete 

[] 

f_Dtau; 

delete 

[] 

i_calc_WN; 

delete 

[] 

wavelengths ; 

delete 

break; 

[] 

levels ; 

default : 

{ 

ErrorLog(4,  "Level=Warning,  Source=signal ,  Message=Invalid 
MODTRAN  message  "); 

break; 

} 

} 

break; 


case  CSSM: 


{ 

switch  (  action  ) 
case  CREATE: 

{ 


{ 


exists . " ) ; 


if  (  cssmActive  )  { 

Scenario_error->LogError ( 3 , " Severity=CAUTION  CSSM  already 
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return  (-999) ; 


if  (  ! cssm_max_X_def ined  | |  ! cssm_max_Y_def ined  | | 

! cssm_max_Z_def ined  | | 

! cssm_dx_def ined  | |  ! cssm_dy_def ined  | | 

! cssm_dz_def ined  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  CSSM  grid 

params  undefined.  "); 


cssm_dz  )  ; 


CSSMObj  =  new  cssm(  cssm_max_X,  cssm_max_Y,  cssm_dx,  cssm_dy. 


CSSMOb j->initialize (cssm: : TIME,  Get Global At tributes ( 

( ScenarioSettings ) NUMTIMES  )); 

CSSMOb j->initialize (cssm: : TIME STEP,  Get Global At tributes ( 
( ScenarioSettings ) TIMESTEP  )); 

assert (  CSSMObj  ) ; 

float  *levels,  *wavelengths ; 

levels  =  new  float [  (int) (cssm_max_Z/cssm_dz )  ]; 

wavelengths  =  new  float[l]; 

for  (  int  i=0;  i<(int) (cssm_max_Z/cssm_dz) ;  i++  )  { 

levels [i]  =  cssm_dz* (float) i; 


cssmOutput 


new  CSSMResults ( 

GetGlobalHeader (  FILEFLAGS  ), 

GetGlobalHeader (  JOBTITLE  ), 

GetGlobalHeader (  EXPID  ), 

GetGlobalHeader (  EXPDATE  ), 

GetGlobalHeader (  EXECUTEDATE  ),  1,1  ) ; 


cssmOutput  ->  putGrid ( 
(int)  (cssm_max_Y/cssm_dy)  , 

( ScenarioSettings ) NUMTIMES  ), 

cssmActive=TRUE; 

break; 

} 


0,  (int)  (cssm_max_X/cssm_dx)  , 

(int) (cssm_max_Z/cssm_dz) , 

(int) GetGlobalAttributes ( 

1,  0.,  0.,  levels,  wavelengths 


)  ; 


case  DESTROY: 

{ 

if  (  IcssmActive  )  { 

ErrorLog(4,  "Level=Warning, 
already  destroyed"); 

}  else  { 

delete  CSSMObj; 
delete  cssmOutput; 
cssmActive  =  FALSE; 

} 

break; 


Source=signal ,  Message=CSSM 
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case  INVOKE: 

{ 

if  (  IcssmActive  )  { 


active . " ) ; 


Scenario_error->LogError ( 5 , " Severity=FATAL  CSSM  not 


}  else  { 


float  *liqWaterContent; 

liqWaterContent  =  new  float [  (int) (cssm_max_X/cssm_dx) 
(int)  (cssin_inax_Y/cssm_dy) 


*  (int) (cssm_max_Z/cssm_dz) 

*  ( int ) GetGlobalAttributes ( 


( ScenarioSettings ) NUMTIMES )  ]; 

assert (  liqWaterContent  )  ; 


■k 


CSSMOb j->  invoke (  liqWaterContent  )  ; 

cssmOutput  ->  putQuan (  "LIQWATER",  "Cloud  liquid  water 
content  (g/kg)",  0,  liqWaterContent  ); 

modelHistory .CSSM=TRUE; 

} 

break; 


default : 


{ 


message . " ) ; 


} 


Scenario_error->LogError ( 4 , " Severity=WARNING  Invalid  CSSM 
break; 


} 

break; 


case  BLIRB: 

{ 

switch  (action)  { 

case  CREATE: 

{ 

if  (  (modelHistory .MODTRAN  | |  IMODTRANActive  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  BLIRB  attempted  w/o 
complete  MODTRAN  data  object."); 

} 

if  (  ! modelHistory . CSSM  | |  IcssmActive  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  BLIRB  attempted  w/o 
CSSM  data  object."); 

} 

if  (  blirbActive  )  { 

Scenario_error->LogError ( 3 , " Severity=CAUTION  Attempt  to  create 
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an  existing  BLIRB  object."); 

return  (-999) ; 

} 

//  Check  to  see  if  the  BLIRB  grid  boundaries  have  been  set  up.  If  they 
haven't,  set 

//  the  parameters  based  upon  what  was  used  by  CSSM.  If  CSSM  wasn't  used  and 
the  grid 

//  parameters  haven't  been  specified,  log  a  fatal  error. 

//  - 


if  (  ! blirb_max_X_def ined 
! blirb_max_Z_def ined  |  | 

! blirb_dx_def ined  | | 


)  { 


I  I  ! blirb_max_Y_def ined  |  | 

! blirb_dy_def ined  | |  ! blirb_dz_def ined 


if 

! cssm_max_Z_def ined  |  | 
! cssm_dz_def ined  )  { 


! cssm_max_X_def ined  | |  ! cssm_max_Y_def ined  | | 

! cssm_dx_def ined  | |  ! cssm_dy_def ined  | | 


endl  ; 

defined  for  BLIRB."); 

} 


cout  <<  "  Fatal  error ... params  undefined.  BLIRB.  "  << 
Scenario_error->LogError ( 5 , " Severity=FATAL  Grid  not 


blirb_max_X  =  cssm_max_X; 
blirb_max_Y  =  cssm_max_Y; 
blirb_max_Z  =  cssm_max_Z; 
blirb_dx  =  cssm_dx; 
blirb_dy  =  cssm_dy; 
blirb_dz  =  cssm_dz; 


blirb_max_X_def ined  =  TRUE; 
blirb_max_Y_def ined  =  TRUE; 
blirb_max_Z_def ined  =  TRUE; 
blirb_dx_def ined  =  TRUE; 
blirb_dy_def ined  =  TRUE; 
blirb_dz_def ined  =  TRUE; 


} 


b 1 i r b_ma x_Y , 
blirb_dz  )  ; 


BLIRBObj  =  new  blirb(  num_times,  timestep,  blirb_max_X, 

blirb_max_Z,  blirb_dx,  blirb_dy. 


assert  (  BLIRBObj  ) ; 

BLIRBObj->  initialize (  blirb :: MODEL, 

GetGlobalAttributes (  (ScenarioSettings) IMODEL)  ); 
float  globalVis  =  GetGlobalAttributes (  (ScenarioSettings) VIS  ); 


if  (  globalVis  >=50.  )  { 

BLIRBObj->  initialize(  blirb: :IVIS,  1.  ); 

}  else  if  (  globalVis  >=  23.  &&  globalVis  <  50.  )  { 
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BLIRBObj->  initialize(  blirb::IVIS,  2.  ); 

}  else  if  (  globalVis  >=  10.  &&  globalVis  <  23.  )  { 

BLIRBObj->  initialize(  blirb::IVIS,  3.  ); 

}  else  if  (  globalVis  >=  5.  &&  globalVis  <  10.  )  { 

BLIRBObj->  initialize(  blirb::IVIS,  4.  ); 

}  else  { 

BLIRBObj->  initialize(  blirb::IVIS,  5.  ); 

} 


BLIRBObj->  initialize (  bl 
GetGlobalAttributes (  (S 
BLIRBObj->  initialize (  bl 
GetGlobalAttributes (  (S 
BLIRBObj->  initialize (  bl 
GetGlobalAttributes (  (S 
BLIRBOb j->  initialize (  bl 
BLIRBOb j->  initialize (  bl 
BLIRBOb j->  initialize (  bl 
Get Global At tribut 
BLIRBOb j->  initialize (  bl 
Get Global At tribut 
BLIRBOb j->  initialize (  bl 
Get Global At tribut 
BLIRBOb j->  initialize (  bl 
Get Global At tribut 
BLIRBOb j->  initialize (  bl 
Get Global At tribut 


irb : : VI , 

cenarioSettings) INITIALWAVENUMBER) 
irb : : V2 , 

cenarioSettings) FINALWAVENUMBER)  ) 
irb : : DV, 

cenarioSettings) DELTAWAVENUMBER)  ) 

irb: :LOWAREA_X,  0,  0.  ); 

irb: :LOWAREA_Y,  0,  0.  ); 

irb: :UPPERAREA_X,  0, 

es  (  ( ScenarioSettings ) BLIRB_MAXX 

irb: :UPPERAREA_Y,  0, 

es  (  ( ScenarioSettings ) BLIRB_MAXY  ) 

irb: :UPPERREG_X,  0, 

es (  ( ScenarioSettings ) BLIRB_MAXX  ) 

irb: :UPPERREG_Y,  0, 

es  (  ( ScenarioSettings ) BLIRB_MAXY  ) 

irb: :UPPERREG_Z,  0, 

es (  ( ScenarioSettings ) BLIRB_MAXZ  ) 


BLIRBObj->  initialize  (  blirb : : THSUN, 

GetGlobalAttributes (  (ScenarioSettings) SOURCEAZIMUTH  )  ) 

BLIRBObj->  initialize  (  blirb :: PHSUN, 

GetGlobalAttributes (  ( ScenarioSettings ) SOURCEZENANGLE  ) 


BLIRBObj->  initialize  (  blirb :: ISOURC, 

GetGlobalAttributes (  ( ScenarioSettings ) SOURCE  )  ); 


BLIRBObj->  initialize  (  blirb :: X_INTERVALS, 

(GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXX  )  / 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_DX  ))); 

BLIRBObj->  initialize  (  blirb :: Y_INTERVALS, 

(GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXY  )  / 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_DY  ))); 

BLIRBOb j->  initialize (  blirb :: Z_INTERVALS, 

(GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXZ  )  / 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_DZ  ))); 

BLIRBObj->  initialize  (  blirb :: X_UPPERBOUND, 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXX  )); 

BLIRBObj->  initialize (  blirb :: Y_UPPERBOUND, 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXY  )); 

BLIRBOb j->  initialize  (  blirb :: Z_UPPERBOUND, 

GetGlobalAttributes (  ( ScenarioSettings ) BLIRB_MAXZ  ) ) ; 


blirbActive=TRUE; 

cout  <<  "BLIRB  Object  has  been  activated."  <<  endl; 


break; 

} 

case  INVOKE: 

{ 

if  (  IblirbActive  )  { 

Scenario_error->LogError ( 3 ,  " Severity=CAUTION  Cannot  invoke 

BLIRB;  object  inactive."); 

return  (-999) ; 

} 

if  (  ImodelHistory .MODTRAN  | |  IMODTRANActive  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  BLIRB  attempted  w/o 
complete  MODTRAN  data  object."); 

} 

if  (  ! modelHistory . CSSM  | |  IcssmActive  )  { 

Scenario_error->LogError ( 5 , " Severity=FATAL  BLIRB  attempted  w/o 
CSSM  data  object."); 

} 


//  blirbOutput  =  new  blirbResults [  8  *  (int)  (blirb_max_X/blirb_dx)  * 
(int) (blirb_max_Y/blirb_dy) 

//  *  (int) (blirb_max_Z/blirb_dz)  ]; 

//  assert (  blirbOutput  ) ; 

BLIRBObj->  invoke (  MODTRANOutput ,  cssmOutput  ); 
modelHistory . BLIRB=TRUE; 

break; 

} 

case  DESTROY: 

{ 

break; 

} 

} 


} 

case  ATMOS : {break;  } 
case  SLAG: 

{ 

switch (action) 

{ 

case  CREATE: 

{ 

if  (  slacActive  )  { 

Scenario_error->LogError ( 3 , " Severity=CAUTION  SLAC  object 
already  exists."); 

return ; 

} 

SLACObj  =  new  slac; 
assert (  SLACObj  ) ; 
slacActive  =  TRUE; 

SLACObj->  initialize (  slac::YEAR,  GetGlobalAttributes ( 

( ScenarioSettings ) YEAR  )  ); 
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SLACObj->  initialize!  slac::MONTH,  GetGlobalAttributes ( 

( ScenarioSettings ) MONTH  )  ); 

SLACObj->  initialize!  slac::DAY,  GetGlobalAttributes! 

! ScenarioSettings ) DAY  )  ); 

SLACObj->  initialize!  slac::HOUR,  GetGlobalAttributes! 

! ScenarioSettings ) HOUR  )  ); 

SLACObj->  initialize!  slac::LAT,  GetGlobalAttributes! 

! ScenarioSettings ) LAT  )  ); 

SLACObj->  initialize!  slac::LON,  GetGlobalAttributes! 

! ScenarioSettings ) LON  )  ); 

break; 

} 

case  INVOKE: 

{ 

if  !  IslacActive  )  { 

Scenario_error->LogError ! 5 , " Severity=FATAL  Cannot  invoke  SLAG 
object  is  inactive."); 

} 


slacOutput  =  new  SLACResults; 
slacOutput  =  SLACObj  ->  invoke!); 
modelHistory . SLAG  =  TRUE; 
SetGlobalAttributes !  SOURCEZENANGLE, 
SetGlobalAttributes (  SOURCEAZIMUTH, 
SetGlobalAttributes  !  MOONPHASE, 
SetGlobalAttributes  !  SOURCE, 
break; 

} 

case  DESTROY: 


slacOutput->zenith  ) ; 
slacOutput->azimuth  ) ; 
slacOutput->lunarPhase  )  ; 
slacOutput->source  )  ; 


if  !  IslacActive  )  { 

Scenario_error->LogError ! 3 , " Severity=CAUTION  Cannot  destroy 
SLAG;  object  is  inactive."); 

return ; 

}  else  { 

delete  SLACObj; 
slacActive  =  FALSE; 

}  break; 

} 

} 

} 


default:  {break;} 

} 

} 


int  Event  ::  signal!  const  MODTRAN : : MODTRAN_mnemonic&  action,  float  value  ) 

{ 

if  !  IMODTRANActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  MODTRAN  object  does  not 
exist."  <<  endl; 

return  1; 
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} 

MODTRANOb j->initialize (  action,  value  ) ; 
return  0; 

} 

int  Event  ::  signal (  const  cssm: : CSSM_mnemonlc&  action,  float  value  ) 

{ 

If  (  IcssmActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  CSSM  object  does  not 
exist."  <<  endl; 

return  1; 

} 

CSSMOb j->initialize (  action,  value  ) ; 
return  0 ; 

} 

float  Event  ::  signal (  const  MODTRAN : : MODTRAN_mneinonlc&  action  ) 

{ 

if  (  IMODTRANActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  MODTRAN  object  does  not 
exist."  <<  endl; 

return  1; 

} 

return  (  MODTRANOb j->initialize (  action  )  ) ; 

} 


int  Event  ::  signal (  const  blirb : : blirb_mnemonic&  action,  float  value  ) 

{ 

If  (  IbllrbActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  BLIRB  object  does  not 
exist."  <<  endl; 

return  1; 

} 

BLIRBOb j->lnitialize (  action,  value  ); 
return  0; 

} 

float  Event  ::  signal (  const  cssm : : CSSM_mnemonlc&  action  ) 

{ 

if  (  IcssmActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  CSSM  object  does  not 
exist."  <<  endl; 

return  1; 

} 

return  (  CSSMOb j->initialize (  action  )  ); 

} 

float  Event  ::  signal (  const  slac : : SLAC_mnemonlc&  action  ) 

{ 

if  (  IslacActive  )  { 
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cout  << 


ERROR:  Initialization  failed...  SLAG  object  does  not 


exist."  <<  endl; 

return  1; 

} 

return  (  SLACOb j->initialize (  action  )  ); 


} 

float  Event  ::  signal (  const  blirb : : blirb_mnemonic&  action  ) 

{ 

if  (  IblirbActive  )  { 

cout  <<  "  ERROR:  Initialization  failed...  BLIRB  object  does  not 
exist."  <<  endl; 

return  1; 

} 

return  (  BLIRBOb j->initialize (  action  )  ); 


void  Event  ::  attach_GUI() 

{ 

string  teststring; 
teststring  =  getenv ( "GUI " ) ; 

cout  <<  "  Value  of  teststring:  "  <<  teststring  <<  endl; 

if  (  teststring  ==  "GUI"  )  { 

system (" /bin/rm  .GUI_command  >&  /dev/null"); 

EventLoop ( ) ; 

}  else  { 

ErrorLog (5, "Severity=Fatal,  Source=attach_GUI ,  message=No  GUI 
detected .  "  )  ; 

cout  <<  "  Not  going  to  go  to  the  event  loop....  problem  detected."  << 

endl  ; 

} 

} 

void  Event  ::  WaitForEvent ( ) 

{ 

do  { 

GUImessage . open (  " . GUI_command" ,  ios : : nocreate  |  ios::in  ); 

}  while  (  GUImessage . fail ( )  ); 

cout  «  "***  INCOMING  MESSAGE  ***"  «  endl; 

GUImessage  »  GUI_MODEL; 

GUImessage  »  GUI_COMMAND; 

GUImessage  »  GUI_VALUE; 

GUImessage . close ( )  ; 

if  (  ( system (" /bin/rm  . GUI_command" ) )  !=  0  )  { 

ErrorLog (5, " Severity=Fatal ,  Source=WaitForEvent ,  message=Messaging 
failure . " )  ; 

} 
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Event  ::  ~Event() 

{ 

} 

void  Event  ::  EventLoopO 

{ 

float  fpValue; 

cout  <<  "  Starting  Event  Loop!"  <<  endl; 

for  (;;)  { 

WaitForEvent () ; 

switch  (  GUI_MODEL  )  { 

case  0 : 

{ 

SetGlobalAttributes (  (ScenarioSettings) GUI_COMMAND,  GUI_VALUE  ); 


break; 

} 

case  1 : 

{ 

signal ( 

(MODTRAN: : MODTRAN_mnemonic ) GUI_COMMAND, 

GUI_VALUE  ) ; 

break; 

} 

// 

case  2  : 

// 

{ 

// 

signal ( 

(CSSM_mnemonic) GUI_COMMAND,  GUI_VALUE  ); 

// 

break; 

// 

} 

// 

case  3: 

// 

{ 

// 

signal ( 

(ATMOS_innemonic)  GUI_COMMAND,  GUI_VALUE  ) 

f 

// 

break; 

// 

} 

// 

case  4  : 

// 

{ 

// 

signal ( 

(BLIRB_innemonic)  GUI_COMMAND,  GUI_VALUE  ) 

f 

// 

break; 

// 

} 

// 

case  5: 

// 

{ 

// 

int  iGUI. 

_value ; 

// 

iGUI_value  =  (int) GUI_VALUE; 

// 

signal ( 

(modelCommand) GUI_COMMAND,  (modelAction) 

iGUI_value  ) ; 

// 

break; 

// 

} 
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} 

} 

} 

7.2  A  Sample  User  Program 


#include  <iostreain .  h> 

#include  <stdlib.h> 

#include  "Event. h" 

main  ( ) 

{ 

//  Dynamically  allocate  a  WAVES  Scenario. 
//  - 

Event  *WAVES_Event ; 

WAVES_Event  =  new  Event (  "TESTCASE", 

"Testing  API", 

"  1 " , 

"199801010000", 
"199801010000"  ) ; 


//  Start  an  event  loop  (if  a  GUI  is  available) . 
//WAVES_Event  ->  attach_GUI ( ) ; 

//  Define  global  parameters. 

//  - 


WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

DAT, 

39. 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

LON, 

-78  . 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

SALE, 

0.20 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

IMODEL, 

6.0 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

IHAZE, 

0. 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

ISEASN, 

0. 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

VIS, 

1. 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

DAY, 

11 . 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

HOUR, 

18  . 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

MONTH, 

6.)  ; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

YEAR, 

1998  . 

) ; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

INITIALWAVENUMBER, 

18100.  ); 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

FINALWAVENUMBER, 

18800.  ); 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

DEL  T AWAVENUMB  E  R , 

50.  )  ; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

NUMSTREAMS,  8 

) ; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

TIMESTEP 

,  1. 

; 

WAVES. 

_Event 

-> 

SetGlobalAttributes ( 

NUMTIMES 

,  1. 

; 

//  Define  CSSM  grid. 
// - 
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WAVES_Event 

WAVES_Event 

WAVES_Event 

WAVES_Event 

WAVES_Event 

WAVES_Event 


->  SetGlobalAttributes ( 
->  SetGlobalAttributes ( 
->  SetGlobalAttributes  ( 
->  SetGlobalAttributes ( 
->  SetGlobalAttributes ( 
->  SetGlobalAttributes ( 


CSSM_MAXX,  5.); 
CSSM_MAXY,  5.); 
CSSM_MAXZ,  5.); 
CSSM_DX,  .50  ); 
CSSM_DY,  .50  ); 
CSSM_DZ,  .50  ); 


//  Define  BLIRB  grid. 
// - 


WAVES_Event  -> 
WAVES_Event  -> 
WAVES_Event  -> 
WAVES_Event  -> 
WAVES_Event  -> 
WAVES_Event  -> 


SetGlobalAttributes ( 
SetGlobalAttributes ( 
SetGlobalAttributes ( 
SetGlobalAttributes ( 
SetGlobalAttributes ( 
SetGlobalAttributes ( 


BLIRB_MAXX,  5.); 
BLIRB_MAXY,  5.); 
BLIRB_MAXZ,  5.); 
BLIRB_DX,  .50  ); 
BLIRB_DY,  .50  ); 
BLIRB_DZ,  .50  ); 


// 


End  of  Global  Parameter  Definition 


//  Create  a  SLAG  instance  and  invoke. 

//  - 

WAVES_Event->  signal (  SLAG, CREATE  ); 

WAVES_Event->  signal (  SLAG, INVOKE  ); 

WAVES_Event->  signal (  SLAG, DESTROY  ); 

//  The  following  command  creates  an  instance  of  MODTRAN,  and 
//  adjusts  MODTRAN  internal  switches  to  match  the  global  settings. 
//  - 


WAVES_Event  ->  signal (  MODTRAN,  CREATE  ) ; 


//  The  global  switches  may  now  be  overridden,  if  necessary. 
//  - 


//  Setup  MODTRAN  for  Solar  Irradiance  calculation. 
//  - 


WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 

WAVES_Event-> 


signal ( 
signal ( 
signal  ( 
signal  ( 
signal  ( 
signal  ( 
signal ( 
signal ( 


MODTRAN 

MODTRAN 

MODTRAN 

MODTRAN 

MODTRAN 

MODTRAN 

MODTRAN 

MODTRAN 


ITYPE,  3.); 
lEMSCT,  3.); 
MULT,  0.); 
TBOUND,  292.); 
H2 ,  0  .  )  ; 

HI,  12.); 
IPARM,  2 . ) ; 
IPH,  2.); 


//  Execute  the  model  for  Solar  Irradiance. 
//  - 

WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 


//  Setup  and  execute  MODTRAN  for  skylight  calculations. 
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// 


WAVES_Event->  signal (  MODTRAN::  PARMl,  (WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  -  225.)  ); 

WAVES_Event->  signal (  MODTRAN::  lEMSCT,  2.); 
WAVES_Event->  signal (  MODTRAN::  MULT,  1 . ) ; 
WAVES_Event->  signal (  MODTRAN::  ANGLE,  54.74  ) ; 
WAVES_Event->  signal (  MODTRAN::  PARM2 ,  WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  ) ; 

WAVES_Event->  signal (  MODTRAN::  H2,  0 . ) ; 

WAVES_Event->  signal (  MODTRAN::  HI,  12.); 
WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 


WAVES_Event->  signal (  MODTRAN::  PARMl,  (WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  -  135.)  )  ; 

WAVES_Event->  signal (  MODTRAN::  ANGLE,  54.74  ) ; 
WAVES_Event->  signal (  MODTRAN::  PARM2 ,  WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  )  ; 

WAVES_Event->  signal (  MODTRAN::  H2,  0 . ) ; 

WAVES_Event->  signal (  MODTRAN::  HI,  12.); 
WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 

WAVES_Event->  signal (  MODTRAN::  PARMl,  (WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  -  315.)  ); 

WAVES_Event->  signal (  MODTRAN::  ANGLE,  54.74  ); 
WAVES_Event->  signal (  MODTRAN::  PARM2 ,  WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  ) ; 

WAVES_Event->  signal (  MODTRAN::  H2,  0.); 

WAVES_Event->  signal (  MODTRAN::  HI,  12.); 

WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 

WAVES_Event->  signal (  MODTRAN::  PARMl,  (WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  -  45.)  ); 

WAVES_Event->  signal (  MODTRAN::  ANGLE,  54.74  ); 
WAVES_Event->  signal (  MODTRAN::  PARM2,  WAVES_Event- 
>GetGlobalAttributes (SOURCEZENANGLE)  ) ; 

WAVES_Event->  signal (  MODTRAN::  H2,  0.); 

WAVES_Event->  signal (  MODTRAN::  HI,  12.); 

WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 

//  Execute  the  model  for  Molecular  Transmittance. 

//  - 


WAVES. 

_Event-> 

signal  (  MODTRAN: 

: ITYPE, 

2.)  ; 

WAVES. 

_Event-> 

signal (  MODTRAN: 

: lEMSCT, 

2.)  ; 

WAVES. 

_Event-> 

signal  (  MODTRAN: 

:  MULT, 

0.)  ; 

WAVES. 

_Event-> 

signal (  MODTRAN: 

: IHAZE, 

0.)  ; 

if  ( 

(WAVES_Event->  signal (  MODTRAN: :H1 

)  )  > 

WAVES_Event->  signal (  MODTRAN: :H2,  12.); 

}  else  { 

WAVES_Event->  signal (  MODTRAN: :H2,  5.  ); 

} 


50 


WAVES. 

_Event-> 

signal ( 

MODTRAN: 

t — 1 

0  . 

)  ; 

WAVES. 

_Event-> 

signal ( 

MODTRAN: 

ANGLE, 

0  . 

)  ; 

WAVES. 

_Event-> 

signal  ( 

MODTRAN: 

I FARM, 

0  . 

) ; 

WAVES. 

_Event-> 

signal  ( 

MODTRAN: 

PARMl , 

WAVES_Event->GetGlobalAttributes (  (ScenarioSettings) LAT  ) 


WAVES_Event->  signal (  MODTRAN::  PARM2 , 

WAVES_Event->GetGlobalAttributes (  (ScenarioSettings) LON  ) 
WAVES_Event  ->  signal (  MODTRAN,  INVOKE  ) ; 


//  Set  up  CSSM. 
// - 


WAVES. 

_Event 

-> 

signal  ( 

CSSM, 

CREATE  )  ; 

WAVES. 

_Event 

-> 

signal ( 

cssm: 

: FCC_NONCUM_l 

,  .  2  )  ; 

WAVES. 

_Event 

-> 

signal ( 

cssm: 

:RANDOMSEED, 

1223.  ) ; 

WAVES. 

_Event 

-> 

signal  ( 

cssm: 

: NONCUM_LAYERS ,  1 .  ) ; 

WAVES. 

_Event 

-> 

signal  ( 

cssm: 

:FCC_CUM,  0. 

)  ; 

WAVES. 

_Event 

-> 

signal  ( 

cssm: 

:BASEMIN,  0.1 

)  ; 

WAVES. 

_Event 

-> 

signal  ( 

cssm: 

:HGTMAX,  4.9 

)  ; 

WAVES. 

_Event 

-> 

signal  ( 

cssm: 

:MAXHEIGHT_1, 

2.0  )  ; 

WAVES. 

_Event 

-> 

signal ( 

cssm: 

:MINHEIGHT_1, 

O 

X — 1 

WAVES. 

_Event 

-> 

signal ( 

cssm: 

:CLOUDTYPE_l, 

1.  ) ; 

WAVES. 

_Event 

-> 

signal  ( 

CSSM, 

INVOKE  ) ; 

//  OK, 
//  — 

finally 

let's  set  up  BLIRB. 

WAVES. 

.Event 

-> 

signal  ( 

BLIRB, 

CREATE  ) 

; 

WAVES. 

.Event 

-> 

signal ( 

blirb : 

: lAERSL, 

18.)  ; 

WAVES. 

.Event 

-> 

signal ( 

blirb : 

:TBOUND, 

300  . ) ; 

WAVES. 

.Event 

-> 

signal  ( 

BLIRB, 

INVOKE  ) 

; 

WAVES. 

.Event 

-> 

signal  ( 

BLIRB, 

DESTROY 

) ; 

//  Finished  with  MODTRAN  and  CSSM. 
//  - 


WAVES_Event  ->  signal (  MODTRAN, 
WAVES_Event  ->  signal (  CSSM  , 
WAVES_Event  ->  signal (  BLIRB  , 


DESTROY  ) ; 
DESTROY  ) ; 
DESTROY  ) ; 


delete  WAVES_Event; 


} 
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Appendix.  Model  Suite  Documentation  Outline 

The  WAVES  software  is  being  documented  through  a  series  of  Army 
Research  Laboratory  technical  reports.  The  general  volumes  planned  are 
outlined  below,  with  short  commentary  on  the  contents  of  each  volume. 

Volume  1  WAVES  Overview 

This  volume  describes  the  general  overview,  capabilities,  and  philosophy 
behind  the  WAVES  suite.  It  also  summarizes  the  other  documentation 
that  is  (or  will  be)  available  for  WAVES. 

Volume  2  User's  Guide 

This  volume  describes  the  use  of  the  WAVES  models  and  guides  both  the 
novice  and  experienced  user  through  the  many  inputs  and  outputs  of  the 
various  models. 

Volume  3  Sample  Scenarios 

Sample  scenarios  are  published  in  this  volume,  which  may  be  updated 
periodically.  These  sample  scenarios  can  be  used  to  test  the  code  for 
extreme  conditions. 

Volume  4  BLIRB  Technical  Documentation 

The  technical  documentation  describes  the  physics  of  the  radiative  trans¬ 
fer  model  in  BLIRB,  as  well  as  the  approximations  and  shortcomings  of 
the  model.  This  information  can  be  found  in  Zardecki  [2,8-10]  and 
Zardecki  and  Davis  [11]. 

Volume  5  ATMOS  Technical  Documentation 

This  report  is  technically  very  similar  to  the  EOSAEL  CN2MAR  report 
published  as  part  of  the  EOSAEL  series  of  technical  reports  [12]. 

Volume  6  3DSMOKE  Technical  Documentation 

The  3DSMOKE  model  is  a  direct  adaptation  of  the  EOSAEL  COMBIC 
model  combined  with  the  STATBIC  texture  model  to  provide  the  inhomo¬ 
geneous  smokes. 

Volume  7  WAVES  ToolKit 

This  volume  describes  utilities  built  to  assist  in  the  use  of  WAVES.  Utili¬ 
ties  are  important  to  the  management  of  the  information  that  must  move 
between  the  various  modules  of  WAVES  [13]. 

Volume  8  Model  Evaluations 

This  volume  is  a  compilation  of  several  model  evaluations  done  on  the 
models  in  WAVES  and  on  WAVES  as  a  suite  of  models.  It  may  contain 
several  sub  volumes  or  parts.  This  information  is  already  in  several  re¬ 
ports  and  papers  (see  Gillepsie  et  al  [14],  Mozer  et  al  [15],  Wells  [16,17], 
Wetmore  et  al  [18],  and  Zardecki  [8,10]). 
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